Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Light reorganisation of the README #10367

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Light reorganisation of the README #10367

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2a1360b
Use hash for headings in the top-level README
Kleidukos Sep 17, 2024
276eea6
Add information about support window for releases
Kleidukos Sep 17, 2024
1214467
Update README.md
Kleidukos Sep 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 19 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,22 @@ This Cabal Git repository contains the following main packages:
The canonical upstream repository is located at
https://github.com/haskell/cabal.

Ways to get the `cabal-install` binary
--------------------------------
## Support window for releases
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'd be great to add the GHC support window info somewhere here too. Because that's what I thought about first time I saw this heading.


| Latest release | 3.14 |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From looking at the rendered version, the first line is treated as a header, which looks a little weird.

Copy link
Collaborator

@geekosaur geekosaur Sep 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would make more sense if it actually stated the support windows and the difference between them. I'd suggest some text, but I only have a vague idea of our actual support windows aside from the comments in validate.yml which I've seen too many times 😀 .

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, also this raises a fairly big problem with LTS releases in our context: support for newer compilers, which (given the way we handle them) requires major version bumps. Do we need to add an escape hatch somewhere for when someone quite reasonably expects an LTS cabal-install to work with a newer ghc?

|---|---|
| Long-Term Support release | 3.12 |

## Learn how to use `cabal` and get support

`cabal` comes with a thorough [User Manual](https://cabal.readthedocs.io).
If you are new to `cabal` and want to quickly learn the basics, check
[Getting Started With Haskell and Cabal](https://cabal.readthedocs.io/en/latest/getting-started.html).

Got questions? Ask in [Haskell Matrix](https://matrix.to/#/#haskell:matrix.org)
(online chat) or [Haskell Discourse](https://discourse.haskell.org).

## Ways to get the `cabal-install` binary

1. _GHCup_ (**preferred**): get GHCup using [the directions on its website](https://www.haskell.org/ghcup/) and run:

Expand All @@ -31,7 +45,7 @@ Ways to get the `cabal-install` binary
2. _[Download from official website](https://www.haskell.org/cabal/download.html)_:
the `cabal-install` binary download for your platform should contain the `cabal` executable.

#### Preview Releases
### Preview Releases

_Getting unreleased versions of `cabal-install`_: gives you a chance to try out yet-unreleased features.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
_Getting unreleased versions of `cabal-install`_: gives you a chance to try out yet-unreleased features.
Getting unreleased versions of `cabal-install` gives you a chance to try out yet-unreleased features.

The colon and italics don't make sense after turning this from a bullet point to a regular paragraph.

Currently, we only provide binaries for `x86_64` platforms.
Expand Down Expand Up @@ -66,8 +80,7 @@ Currently, we only provide binaries for `x86_64` platforms.
from the `Validate` worklow page on GitHub, at the very bottom of the page,
or from the `build-alpine` workflow for statically linked Linux builds.

Ways to build `cabal-install` for everyday use
--------------------------------------------
## Ways to build `cabal-install` for everyday use

1. _With cabal-install_:
if you have a pre-existing version of `cabal-install`, run:
Expand All @@ -91,17 +104,6 @@ Ways to build `cabal-install` for everyday use
if you don't have a pre-existing version of `cabal-install`,
look into the [`bootstrap`](bootstrap) directory.

Learn how to use `cabal` and get support
----------------------------------------

`cabal` comes with a thorough [User Manual](https://cabal.readthedocs.io).
If you are new to `cabal` and want to quickly learn the basics, check
[Getting Started With Haskell and Cabal](https://cabal.readthedocs.io/en/latest/getting-started.html).

Got questions? Ask in [Haskell Matrix](https://matrix.to/#/#haskell:matrix.org)
(online chat) or [Haskell Discourse](https://discourse.haskell.org).

Build for hacking and contributing to cabal
-------------------------------------------
## Contributing to cabal
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I like this much more than the previous version! Maybe, backtickize cabal?

Suggested change
## Contributing to cabal
## Contributing to `cabal`


Refer to [CONTRIBUTING.md](CONTRIBUTING.md).
Loading