You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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.
Activity
pllim commentedon Jul 16, 2023
I think we agreed on the following:
Ways to do change log:
stefanv commentedon Jul 16, 2023
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 commentedon Sep 18, 2023
Saw this in ics-py release notes: https://keepachangelog.com/en/1.0.0/
pllim commentedon Sep 18, 2023
Does this mean our work is done? Hard for me to tell who wrote that though.
lagru commentedon Oct 3, 2023
Re who wrote it, you can find the repo and its author here https://github.com/olivierlacan/keep-a-changelog.
InessaPawson commentedon Oct 16, 2023
IMHO it still would be helpful to have a dedicated SPEC to bring visibility to this topic in our ecosystem.
InessaPawson commentedon Jun 3, 2024
@pllim @stefanv @lagru I'll be working on a draft for this SPEC during the 2024 Scientific Python Summit. This will be SPEC10.
[-]SPEC on change log[/-][+]SPEC 0010 on changelog[/+][-]SPEC 0010 on changelog[/-][+]SPEC10 on release documentation[/+][-]SPEC10 on release documentation[/-][+]SPEC10: changelog and release documentation[/+]InessaPawson commentedon Jun 11, 2024
@pllim After the discussion at the 2024 Scientific Python Developer Summit, this document doesn't seem to be very helpful for our ecosystem.
InessaPawson commentedon Jun 11, 2024
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.