SPEC10: changelog and release documentation

[pllim]

As discussed briefly during Scipy 2023. cc @bsipocz @lagru

after all we were asked for opinionated ideas

be careful what you wish for

Might be useful. Even if just to collect/build community consensus what should be present in release notes and how best to achieve that!

[pllim]

I think we agreed on the following:

• High level recommendations on best practices. Don't dwell into details that can get outdated fast.
• Change log is meant for users. Therefore, it should not include things like test changes, doc changes, refactoring without any functionality changes.
• There are different ways to do change log and it depends on how active a project is and the number of contributors.

Ways to do change log:

• Use GitHub built-in release notes generation at release time. It is available during GitHub Release step. Very easy to use but you cannot see the change log until release time and the auto generated text needs cleaning. It also only captures PRs, not direct pushes that are not recommended anyway.
• lagru's Action to build change log from commits. bsipocz and lagru can fill out details here.
• A single CHANGES.rst file that contributors edit by hand. Change log is ready to go on main whenever. But high risk to cause PR merge conflict if lots of activity. Entries need to be moved manually if PR misses milestone. Need extra script for consistency check. Milestone check needs to be refactored to work with auto milestone that is applied only after merge.
• towncrier fragments. Do not cause merge conflict. Can be rendered into change log on RTD using sphinx-changelog in OpenAstronomy but the rendered version is not fed back to main. Final rendered change log is done at release time on release branch, which will also delete rendered fragments. This rendering then needs to be forwardported to main. Too heavyweight for simple projects. Sometimes new towncrier release breaks our stuff.

[stefanv]

Thanks for taking on this topic. It'd be interesting to see what coalesces out of all the opinions.

Re principle 2, I'd say leave decisions of what to include to the project. There are some essentials (API changes etc.) but then doc updates etc. will depend on how fine grained the project wishes to be.

[stefanv]

Saw this in ics-py release notes: https://keepachangelog.com/en/1.0.0/

[pllim]

Does this mean our work is done? Hard for me to tell who wrote that though.

[lagru]

Re who wrote it, you can find the repo and its author here https://github.com/olivierlacan/keep-a-changelog.

[InessaPawson]

IMHO it still would be helpful to have a dedicated SPEC to bring visibility to this topic in our ecosystem.

[InessaPawson]

@pllim @stefanv @lagru I'll be working on a draft for this SPEC during the 2024 Scientific Python Summit. This will be SPEC10.

[InessaPawson]

Does this mean our work is done?

@pllim After the discussion at the 2024 Scientific Python Developer Summit, this document doesn't seem to be very helpful for our ecosystem.

[InessaPawson]

As per a conversation with @bsipocz at the 2024 Scientific Python Developer Summit, the current draft of the SPEC includes recommendations for changelog and release documentation. If it gets too long, we might split the document in two SPECs.