Changelogs for packages aren't documented

[geekosaur]

What is wrong with the docs?
According to a user in #hackage:matrix.org, nowhere is it documented that Hackage requires packages to have a changelog file, nor what this involves.

Additional context

[24 09:40:50]  <mauke> the other day hackage complained that my package doesn't have a changelog
[24 09:41:03]  <mauke> what is a changelog, where does hackage look for it, and where is this documented?
[24 09:52:13]  <haskellbridge> <H​écate> mauke: https://en.wikipedia.org/wiki/Changelog
[24 09:52:43]  <haskellbridge> <H​écate> CHANGELOG.md is a good place to have your changelog
[24 09:53:36]  <haskellbridge> <H​écate> and I believe it has to be put in https://cabal.readthedocs.io/en/stable/cabal-package-description-file.html#pkg-field-extra-doc-files
[24 09:53:47]  <haskellbridge> <H​écate> mauke: run "cabal check" I think it'll tell you more
[24 09:54:17]  <mauke> cabal check just says "No errors or warnings could be found in the package."
[24 10:34:37]  <haskellbridge> <m​auke> I can't find changelog anywhere in the cabal documentation. Or hackage. 
[24 10:54:58]  <haskellbridge> <f​-a> mauke: please tell us your "cabal --version"
[24 10:59:45]  <haskellbridge> <f​-a> This is the pr #8497 (https://github.com/haskell/cabal/pull/8747) (alas, missing a changelog itself!)

[philderbeast]

I used cabal init --non-interactive¹ and then deleted the CHANGELOG.md and its reference in the package description .cabal file. Rerunning cabal sdist works the same as it did before the deletion, writing the tarball. The sdist command is not checking that there is a change log.

The output of cabal sdist and cabal check after the deletion:

$ cabal sdist
Wrote tarball sdist to
/.../changelog-required?/dist-newstyle/sdist/changelog-required-0.1.0.0.tar.gz

$ cabal check
These warnings will likely cause trouble when distributing the package:
Warning: [no-category] No 'category' field.
The following errors will cause portability problems on other environments:
Error: [no-syn-desc] No 'synopsis' or 'description' field.
Error: [license-none] The 'license' field is missing or is NONE.
Error: Hackage would reject this package.

Footnotes

1. I used this command cabal init "changelog-required?" --non-interactive and note that cabal init stripped the ? character from the project root name for the package name. ↩

[ffaf1]

I tried to upload a package candidate without changelog to Hackage, it works:

f@x270:~/download/lentil-1.5.8.0$ cabal upload /home/f/download/lentil-1.5.8.0/dist-newstyle/sdist/lentil-1.5.8.0.tar.gz
Warning: this is a debug build of cabal-install with assertions enabled.
Uploading
/home/f/download/lentil-1.5.8.0/dist-newstyle/sdist/lentil-1.5.8.0.tar.gz...
Package successfully uploaded as candidate. You can now preview the result at
'https://hackage.haskell.org/package/lentil-1.5.8.0/candidate'. To publish the
candidate, use 'cabal upload --publish'.
f@x270:~/download/lentil-1.5.8.0$ ls
dist-newstyle  doc  lentil.cabal  LICENSE  README  Setup.hs  src  stack.yaml  test

I will ask the user for more informations.

[ffaf1]

More from the user.
If you upload a package without changelog, Hackage shows the field with “None Available” in bold/red.

<user> ah, yes. that was the red notice I remember
<user> it caught my eye because I was following the cabal and hackage documentation to make sure I'd added all the required <user> fields, and then suddenly this "Change log" property shows up in red
<user> when it has never been mentioned before

I wonder how suggestive cabal check should be.
Pestering the user to add a changelog file will lead to a number of changelog being there, but not actually being updated.

[ulysses4ever]

I don't believe changelogs are mandatory on Hackage (e.g. here's a package without one uploaded in 2020: https://hackage.haskell.org/package/BNFC-meta).

[ulysses4ever]

I wonder how suggestive cabal check should be.
Pestering the user to add a changelog file will lead to a number of changelog being there, but not actually being updated.

Well, pestering is not the right approach, of course. But helpfully suggest to consider adding one so that the users have an idea how this release progresses from the previous one would be good imo.

[geekosaur]

While this is all cogent, it's missing the user's (and my, cf. the title I chose for this issue) point: it's not documented.

[ffaf1]

While this is all cogent, it's missing the user's (and my, cf. the title I chose for this issue) point: it's not documented.

I hate the “not our problem” attitude, especially in tightly integrated tools, but is there anything we should do here, doc-wise?
This is something Hackage does, something that is presentational and will not prevent you from uploading a package.

cabal init also already creates a CHANGELOG.md plus extra-doc-file entry in the manifest, so from an UX POV you need to actively remove those, not something you stumble upon by chance.

That would be different of course if we were to create a new warning, then documentation would be necessary.

[geekosaur]

I am not saying "not our problem". I am saying that our documentation should explain the changelog field (urp! there isn't one, as noted below) in cabal files, since it seems this is sparse at best.

(In fact, I am finding that changelogs are apparently inferred from the contents of extra-doc-files and, as the original user states, not documented at all.)

The ideal situation would probably be to bump the spec and add an explicit changelog field to cabal files. I suspect this is asking too much at this point, though (the horse has already bolted this barn, it's too late to block the door). Some documentation about changelogs, including something about the way they're inferred (the ticket you mentioned on Matrix earlier seems to be related to this?), would be a good idea.

This does not include explaining changelog best practices and such, though, except by finding and pointing to a stable link about such practices.

[ffaf1]

Some documentation about changelogs, including something about the way they're inferred

Alas they are inferred in two different ways, cabal does one thing and Hackage does a similar (but not equivalent) thing.

I note there is a (tiny, not fully explained) changelog reference in the cabal check docs:

no-docs: missing expected documentation files (changelog).

(this is only tangent to this ticket tho, i.e. the case where changelos is present in the working directory but not in the .cabal file).

I will make a patch to expand this bit, for sure. edit: done

[mauke]

cabal init also already creates a CHANGELOG.md plus extra-doc-file entry in the manifest, so from an UX POV you need to actively remove those, not something you stumble upon by chance.

That's a relatively recent feature. As far as I can tell, creation of a changelog was only added to cabal-install in 4d6175c (from 2015, probably v1.24?). My package is older than that.

(For extra irony, the cabal-install changelog does not mention when cabal init started generating changelogs.)