Switch to Towncrier - #11279

Also the main change that should be done if we go this way is to split the changelog in one changelog per version. (And where should we put those ?)

@saimn - thanks for this proof of concept! This helps a lot and I'm happy enough to consider going this way.

I like the sub-sections as permanent directories. That serves a good purpose of defining available subsections.

The concern about not being able to see the rendered version of the change log in master (on GitHub) still applies, i.e. there is not any easy way to see a summary of all the changes that have been committed to the release. One option is to just accept that and say you need to go into a terminal and use towncrier to generate the updates. But as a typical user this is a bit tricky because you need to grab the milestone from GitHub for the summary to be accurate. I do frequently look at the recent changes in the changelog, so we don't want to give up on that capability too quickly (though of course other projects seem to manage).

Another smaller issue is the case of multiple PRs that belong to one change. This happens sometimes for very big changes where you have the main PR and then one or more follow-on PR's to address known issues that came up in review. It can also happen with bugs in a PR that were fixed in dev before release. Will there be any way to allow this?

One more concern to discuss is the migration from a single entire-history changelog to per-version changelogs. Since the community has come to expect the entire-history changelog and may have links to this file in different places, we have to be aware of breakage like that.

There is also the issue that finding the version associated with some change by a text search in CHANGES.rst is no longer easy. Not a showstopper but still a change to consider.

The concern about not being able to see the rendered version of the change log in master (on GitHub) still applies

While not perfect, SunPy solves this with a sphinx extension which renders it to our documentation: https://docs.sunpy.org/en/latest/whatsnew/changelog.html which shows you everything that's in the log since the last release.

Which I now see that @saimn has done something similar to here 🤦. I would be happy to move that sphinx extension out to openastronomy if you are going to use it.

And to be clear, I'm just applying a high bar for making a change like this in my comments, but I'm generally 👍 on this and very happy that @saimn took the initiative to actually show this can work for us!

There is also the issue that finding the version associated with some change by a text search in CHANGES.rst is no longer easy. Not a showstopper but still a change to consider.

This is true once the release is done and the final log rendered? or am I missing something?

This is true once the release is done and the final log rendered? or am I missing something?

I got the impression there will be only per-version changelogs (not a single comprehensive one), so if you don't know which version the change was in then you have to search through files. But I might not be understanding.

I haven't looked through the changes in this PR in detail, but sunpy still renders out to a single file on release: https://github.com/sunpy/sunpy/blob/master/CHANGELOG.rst

I haven't been carefully following that other issue and I never used towncrier. But just looking at the diff here, there is no indication of milestone anywhere and yet it magically know all these files are for 4.3; how? Are the some post-release re-organizing that need to happen?

How painful is it:

1. For PR author to move the change log of unmerged PR when its milestone is moved?
2. For us to update the change log bot to check that change log needs to be there or is correct?

Also, has towncrier ever introduce breaking change that needs downstream to refactor entries?

(If any of these has been discussed before, linking to the discussion is sufficient. Thanks!)

p.s. Thanks a lot for this PR, @saimn ! It is good to see some ideas becoming concrete here.

But just looking at the diff here, there is no indication of milestone anywhere and yet it magically know all these files are for 4.3; how

You assign the release to the entries at render time, this is the key component of towncrier to me. An entry has no version associated with it until that version is released with the fragement included. This means there is no issuies with backporting changelog entries they come along for the ride and then are assigned to the version as part of the release procedure.

For us to update the change log bot to check that change log needs to be there or is correct?

Baldrick/Giles supports verifying the presence of a towncrier changelog entry and that the number matches the PR and that the type is one of the allowed types.

You assign the release to the entries at render time

Can you please clarify -- So the release manager renders it, and then put the rendered file under version control?

This also means, we need to implement this solution for 4.0.x and 4.2.x branches? Otherwise, the release manager needs to handle two different change log mechanisms.

Great to see that you're happy with this @taldcroft :)

The concern about not being able to see the rendered version of the change log in master (on GitHub) still applies

The Sphinx extension seems a good solution. Would be great if you can move it to a dedicated package @Cadair (also I don't understand your comment "Which I now see that @saimn has done something similar to here". There is no sphinx extension in my PR ?)

Another smaller issue is the case of multiple PRs that belong to one change.

It is possible to have duplicated fragments with different PR number or sections/types. For example when converting the existing changs for 4.3 to fragments, some entries have two PR/issue numbers, which I converted to two fragment files:

❯ cat docs/changes/io.fits/11149.feature.rst
Added ``append`` keyword to append table objects to an existing FITS file
❯ cat docs/changes/io.fits/2632.feature.rst 
Added ``append`` keyword to append table objects to an existing FITS file

And towncrier correctly renders this :

- Added ``append`` keyword to append table objects to an existing FITS file [#2632, #11149]

I haven't looked through the changes in this PR in detail, but sunpy still renders out to a single file on release: https://github.com/sunpy/sunpy/blob/master/CHANGELOG.rst

Great, I did not know that was possible!

@pllim - About milestones, that's the killer feature with towncrier, there is no need to deal with it. Each PR must have a "changelog fragment", for example:

❯ cat docs/changes/io.fits/11149.feature.rst
Added ``append`` keyword to append table objects to an existing FITS file

Then the PR can be backported with its fragment, or included in the release branch. And when doing the release the changelog is rendered (with the towncrier build command) and all the fragment in docs/changes/ are included. And then the fragments are deleted (towncrier build can delete them). So this way each release branch contains the fragments for the PRs that are included in the branch.

Also, has towncrier ever introduce breaking change that needs downstream to refactor entries?

I don't think so. The content of the file is just plain RST that will go in the final changelog file. What could change a bit is the syntax for the filename, but the changes I've seen are mostly adding flexibility with more options to customize it.

I don't understand your comment "Which I now see that @saimn has done something similar to here"

oh I think I looked at the changelog template and thought it was a docs thing because of the path.

Would be great if you can move it to a dedicated package

I am happy to put the effort into doing this, but only after this PR gets enough approval behind it that I am confident it will actually be needed ;)

Can you please clarify -- So the release manager renders it, and then put the rendered file under version control?

The flow for sunpy is as follows:

• PRs come with one or more associated fragment files.
• The feature branch is made, all of the fragment files on the main branch are removed.
• As part of the final release the command towncrier --version vX.Y.Z is run which renders the changelog to a new section at the front of our CHANGELOG.rst file.
• All the fragement files are deleted (as part of the above command)
• The rendered changelog and the removal of the fragments are committed and released.

Any backports have their fragment files backported with the code changes, and these fragment files are deleted from the release branches at the time of release.

This also means, we need to implement this solution for 4.0.x and 4.2.x branches? Otherwise, the release manager needs to handle two different change log mechanisms.

If a bugfix release of those branches was made aligned with the transition all future release of those branches would be able to just start using the new flow without any further changes (i.e. towncrier becomes the WIP changelog section at the top of the file for those branches after that release). If that didn't happen any WIP changelog entries would need converting to fragments.

#yolo

🚀 !! I think it would be good to follow up @pllim 's email to astropy-dev on March 1 with another saying this has now happened.

To close the loop, @saimn posted this follow up on the mailing list. Thank you, all!

Hi everyone,

The pull request has been merged so astropy is now using towncrier [1] to manage its changelog. If you have a pull request open with the old changelog system you must update it to the new system:

• rebase on master
• create the fragment file as explained in docs/changes/README.rst [2]
• revert changes in the CHANGES.rst file : git checkout master -- CHANGES.rst
• commit. If the old changelog was added in the last commit, use --amend

Simon

[1] https://github.com/twisted/towncrier
[2] https://github.com/astropy/astropy/blob/master/docs/changes/README.rst