Light reorganisation of the README #10367

Kleidukos · 2024-09-17T11:48:17Z

No description provided.

ulysses4ever · 2024-09-17T17:13:41Z

README.md

--------------------------------
+## Support window for releases
+
+| Latest release | 3.14 |


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

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 😀 .

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?

ulysses4ever · 2024-09-17T17:15:17Z

README.md

+
+| Latest release | 3.14 |
+|---|---|
+| Long-Time Support release | 3.12 |


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.

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 Cabal or cabal-install releases. Previously, the GHCup maintainer 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.

It's a good start, I guess, thank you. It feels vague because LTS policies usually have exact time frames.

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.

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.

README.md

ulysses4ever · 2024-09-17T17:19:23Z

README.md

@@ -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.


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.

ulysses4ever · 2024-09-17T17:20:34Z

README.md

-
-Build for hacking and contributing to cabal
-------------------------------------------
+## Contributing to cabal


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

Suggested change

## Contributing to cabal

## Contributing to `cabal`

README.md

ulysses4ever · 2024-09-19T13:17:55Z

I just realized that README is still inconsistent w.r.t. cabal vs. cabal-install. It probably should use one of these to mean the tool? And I'm less sure about how to designate Cabal, the project. I'd prefer "Cabal" (no backticks to avoid too much similarity to cabal(-install)) but I think Mikolaj expressed concerns about that in the past (?).

Kleidukos · 2024-09-19T13:25:07Z

@Mikolaj do you still have concerned about the typographical differences between the Cabal project, and the cabal executable?

Mikolaj · 2024-09-19T22:57:07Z

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.

ulysses4ever · 2024-11-07T01:51:43Z

@Kleidukos do you want to revisit it? There are a couple of small issues in markup (see my comments above) but other than it'd be a shame to leave it behind...

Kleidukos · 2024-11-07T10:58:39Z

Yes I'll get back to it, thanks

Mikolaj · 2025-03-13T11:01:46Z

@Kleidukos: pretty ping? :)

Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>

Kleidukos · 2025-03-13T12:09:18Z

@Mikolaj don't be shy now, it's your turn ;-)

ulysses4ever

Thanks for resuming the work on it!

Good readme's are hard. I have a bunch of suggestions that hopefully could move it in the right direction a bit more.

ulysses4ever · 2025-03-13T18:51:27Z

README.md

-This Cabal Git repository contains the following main packages:
+This repository contains the following packages:


The word "main" was making a point that there's more than that and indeed there is. I agree that it's maybe not the most important piece of info but I was surprised when I learned how many packages are hosted in this repo :'-)

ulysses4ever · 2025-03-13T18:55:26Z

README.md

+<dl>
+    <dt>Latest release</dt>
+    <dd>3.14</dd>
+    <dt>Long-Term Support release</dt>
+    <dd>3.12</dd>
+</dl>


Another piece of info that has to be maintained every release, sigh... A more effective way to convey latest release is to make sure github releases are keeping up (there aren't usually).

As before, I'm against introducing the term LTS without a definition. I also don't see enough human-power to support yet another concept.

Lastly, this block takes an enourmous amount of space but only gives two numbers, one of which (LTS) is about an under-specified thing that's not necessarily relevant for most people. The other number most people will look up by looking at the releases pane in the github sidebar. I don't think this block pulls its own weight.

Also, why "support window", what's window'y in these two numbers? Does it mean we support all versions between latest and LTS? I hope not. Overall, if this whole block survives (I hope not), the heading should be changed.

ulysses4ever · 2025-03-13T18:57:39Z

README.md

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


Should we advertize issues/discussions here? I personally like to answer Cabal questions but I very partially read Discourse and in Matrix anything can bubble up pretty quickly. I do monitor new issues/discussions here. So, I'd prefer it be mentioned here. Maybe it's personal...

ulysses4ever · 2025-03-13T18:58:38Z

README.md

+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


It's cabal in the previous heading and cabal-install here. Can we have it standardized at least inside one document, please?

ulysses4ever · 2025-03-13T18:59:28Z

README.md


-_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.


Suggested change

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

Getting _unreleased versions_ of `cabal-install` allows you to try out yet-unreleased features.

ulysses4ever · 2025-03-13T19:00:29Z

README.md

-
-Build for hacking and contributing to cabal
-------------------------------------------
+## Contributing to `cabal`


Same cabal/cabal-install mish-mash in this heading vs. the previous.

Mikolaj

Lets wait with this until the comments are resolved and until we confirm that we want to advertise 3.12 to be the LTS.

Mikolaj · 2025-04-10T18:05:27Z

Related to this PR: we've decided in todays' devs meeting that cabal LTS is postponed until the idea is rethought and maybe until GHC has regular LTS releases and we can piggy-back or something. So, advertising LTS in the README may be premature.

Kleidukos added 2 commits September 17, 2024 13:42

Use hash for headings in the top-level README

2a1360b

Add information about support window for releases

276eea6

geekosaur approved these changes Sep 17, 2024

View reviewed changes

jasagredo approved these changes Sep 17, 2024

View reviewed changes

ulysses4ever reviewed Sep 17, 2024

View reviewed changes

geekosaur reviewed Sep 17, 2024

View reviewed changes

README.md Outdated Show resolved Hide resolved

Update README.md

b1c2536

Co-authored-by: brandon s allbery kf8nh <allbery.b@gmail.com>

Kleidukos force-pushed the rework-readme branch from bc574b4 to b1c2536 Compare March 13, 2025 11:28

Try another formatting for release windows

d2d8ba2

Kleidukos requested a review from ulysses4ever March 13, 2025 11:30

Merge branch 'master' into rework-readme

243a1f9

Kleidukos requested a review from Mikolaj March 13, 2025 11:35

ulysses4ever reviewed Mar 13, 2025

View reviewed changes

Mikolaj requested changes Mar 29, 2025

View reviewed changes

	_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.

		This Cabal Git repository contains the following main packages:
		This repository contains the following packages:

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

	_Getting unreleased versions of `cabal-install`_ gives you a chance to try out yet-unreleased features.
	Getting _unreleased versions_ of `cabal-install` allows you to try out yet-unreleased features.

Light reorganisation of the README #10367

Are you sure you want to change the base?

Light reorganisation of the README #10367

Uh oh!

Conversation

Kleidukos commented Sep 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

geekosaur Sep 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ulysses4ever Sep 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

geekosaur Sep 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ulysses4ever commented Sep 19, 2024

Uh oh!

Kleidukos commented Sep 19, 2024

Uh oh!

Mikolaj commented Sep 19, 2024

Uh oh!

ulysses4ever commented Nov 7, 2024

Uh oh!

Kleidukos commented Nov 7, 2024

Uh oh!

Mikolaj commented Mar 13, 2025

Uh oh!

Kleidukos commented Mar 13, 2025

Uh oh!

ulysses4ever left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mikolaj left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mikolaj commented Apr 10, 2025

Uh oh!

Uh oh!

Kleidukos commented Sep 17, 2024 •

edited

Loading

geekosaur Sep 17, 2024 •

edited

Loading

ulysses4ever Sep 17, 2024 •

edited

Loading

geekosaur Sep 17, 2024 •

edited

Loading

Mikolaj left a comment •

edited

Loading