How to add a changelog to a Cabal package?

Question

I see that Hackage 2 has a changelog field. This is a feature I've wanted for a long time. But multiple Google searches have failed to find a single shred of documentation about how you populate this field. Does anyone know how to do it?

Answer 1

I could not find documentation right away, but code:

There is no field for it, but it will simply look in the tarball for a file named changelog, change_log or changes (a file ending of .txt, .md and .markdown is allowed). Case does not matter.

Note that this file won't necessarily be added to the tarball by cabal sdist unless you also add it to the cabal file somehow. One way to do this is by adding it to the Extra-source-files: field at the top-level of the cabal file. e.g.:

Extra-Source-Files:  changelog.md 

Cabal's .cabal file does this, and provides a good example.