cabal

cabal copied to clipboard

How do we report known issues with released versions of cabal-install in a way that end users of cabal-install might notice?

From a search of this repo, I found "known issues" in the output of the hidden man command. That cabal-install label has 0 Open and 0 Closed issues. Is that the right label?

Up on hackage there's the changelog but what's the best way to alert users of a known issues with packages on hackage short of deprecating the release on hackage, do a revision and amend the changelog or something else?

$ cabal man
...
BUGS
       To  browse  the  list  of  known  issues or report a new one please see
       https://github.com/haskell/cabal/labels/cabal‐install.
...

• Amend the changelog: On hackage, the cabal changelog redirects to this repository's release-notes via plain text display of links that are not clickable but these release notes are generated, aren't they? How would we then add a known issue as an addendum?

[!NOTE] -*-change-log-*-

3.10.3.0 Hécate <hecate+github@glitchbra.in> January 2024

• See https://github.com/haskell/cabal/blob/master/release-notes/cabal-install-3.10.3.0.md

3.10.2.1 Hécate <hecate+github@glitchbra.in> November 2023

• See https://github.com/haskell/cabal/blob/master/release-notes/cabal-install-3.10.2.1.md

• Add known issues to the docs: https://cabal.readthedocs.io/en/3.10/ doesn't have a release notes or know issues section. By comparison the GHC users guide does have a known issues section but this wouldn't be updated after a release would it?

Problem with “Known issues” lists is that they get stale easily. E.g. GHC known issues section lists #12971 but that has been closed since then.

I don't know whether github supports regexps or search patterns to get all cabal-install; cmd/xyz labels.

I most often get cabal-install via ghcup tui these days. This does have a link to the changlog and that goes straight to the release notes on this repo for the cabal version selected, e.g. those for cabal-install-3.10.3.0.

I have a very grumpy opinion on this matter.

There are two kind of people, the ones which know how to use search, google and know how to read; and then all the other people.

For the first category it's "enough" to keep a good track of issues. What is fixed and when, what isn't; which versions fixes are backported to etc. But just having complete changelogs are a very good start (including clean git log). It's not an easy task, but it's an minimum requirement. GitHub issues has a very limited way to add any metadata (e.g. no way to add metadata like in which version the bug was found and in which it's fixed), so doing that is difficult.

The second group of people will open an issue, ask on reddit, discourse etc. Then someone from the first group of people can find an issue for them and tell about it. In other words, you need to empower first group.

TL;DR, you first need to have the data, keep it organised, and only then you can think about how to best present it.

To highlight my point: https://github.com/haskell/cabal/issues/9952 is exactly "a known issue", but it wasn't recorded anywhere.

I think the best way to signal known issues currently is the start of our changelogs, also called release notes, that live on master branch. They are editable via PRs. The only problem is that they are created during the release process, not before, so we'd need a place to stage known issues initially. Maybe just create that file ahead of the time with the only content being known issues?

Regarding links, note that the Cabal Hackage package changelog is in .md format and has clickable links. Obviously cabal-install and cabal-install-solver should have their Hackage changelog files converted to that style and it'd be clickable as well. I don't know if there's an issue about that but if it is, it's many years old.