Light reorganisation of the README #10367
Conversation
| -------------------------------- | ||
| ## Support window for releases | ||
|
|
||
| | Latest release | 3.14 | |
There was a problem hiding this comment.
From looking at the rendered version, the first line is treated as a header, which looks a little weird.
There was a problem hiding this comment.
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 😀 .
There was a problem hiding this comment.
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?
README.md
Outdated
|
|
||
| | Latest release | 3.14 | | ||
| |---|---| | ||
| | Long-Time Support release | 3.12 | |
There was a problem hiding this comment.
As I said in the past: I'm mildly against using the term LTS without having any concrete definition for it. Here would be a great place for a short definition btw. But I don't know what it should be, from the top of my head.
There was a problem hiding this comment.
We intend long-term support (LTS) releases to be stable releases with ongoing support, for use by projects which can't reasonably follow a moving target of
Cabalorcabal-installreleases. Previously, theGHCupmaintainer was lightly maintaining 3.6 as a stable release, but it's unreasonable to expect him to do so for new releases, so we are providing a maintained stable release ourselves. New LTS major releases will happen as needed, but as yet we have not determined when because we don't have a good feel for how often it will be needed. The LTS release will receive major bug fixes but avoid breaking changes, which will require a new LTS series.
An example would be the 3.14 release that's in progress (or just happened?), which is fairly close on the heels of 3.12.1.0. I can well imagine other projects wanting to stick to a stable but maintained release.
There was a problem hiding this comment.
It's a good start, I guess, thank you. It feels vague because LTS policies usually have exact time frames.
There was a problem hiding this comment.
That's because it is vague, and states why it is vague ("as yet we have not determined…"). We weren't even sure 3.12 would be an LTS branch at release time.
There was a problem hiding this comment.
As for timeframes, we need to find out how hard ghc releases will be pushing us along before we know how long-term the long-term support branches need to be in order to be meaningful. The only thing I can say for certain at this point is that something Ubuntu-like won't work either in terms of time or version numbers. As such, maybe it's best to state that our LTS branch is experimental for now.
| @@ -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 | |||
There was a problem hiding this comment.
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.
| @@ -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. | |||
There was a problem hiding this comment.
| _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.
|
|
||
| Build for hacking and contributing to cabal | ||
| ------------------------------------------- | ||
| ## Contributing to cabal |
There was a problem hiding this comment.
Thanks, I like this much more than the previous version! Maybe, backtickize cabal?
| ## Contributing to cabal | |
| ## Contributing to `cabal` |
|
I just realized that README is still inconsistent w.r.t. |
Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>
|
@Mikolaj do you still have concerned about the typographical differences between the Cabal project, and the |
|
Yes, IIRC, I preferred "cabal" to "Cabal" as the project name, mostly on historic grounds and also because we have "Cabal the library" and also because "the Grep project" sounds silly and cabal is, most visibly, a commandline tool, so it's rather like "grep" than "Firefox". But I defer to the PR author --- improving the README is much more important than such details. |
#characters consistently in the README to mark headings