Switch from Reno to Towncrier for release notes

[Eric-Arellano]

Why Reno broke

Closes Qiskit/documentation#979 and Qiskit/documentation#978.

Reno stopped working correctly with Runtime 0.21. The release notes for 0.16+ were all being included in the 0.15 release note entry, incorrectly. #1486 attempted to fix this and it worked locally, but in CI the stable/0.15 entry was missing all release notes before 0.15 and we could not figure out how to fix that.

Reno got into a bad state because of the feature branch experimental-0.2. That branch was based off of main at the time of 0.15.0. It was not merged back into main until preparing 0.21.0 when we merged 32b0dbc into main . During the feature branch's life, ec8f5a4 merged main into experimental-0.2, which we think messed things up by copying over Git tags into the feature branch. git log --tags --simplify-by-decoration shows all the tags in order, but between 0.20.0 and 0.21.0 is that commit ec8f5a4.

We think the problem is that Reno gets confused when you merge a branch that itself has Git tags back into main. This blog warns

There is one case when reno may skip release note, and it’s a single known ‘don’t do it’ case, documented and articulated: Do not merge stable branch with release tags back into master branch.

We think Reno ended up confusing some of the same Git tags between the feature branch and main.

We could not think of a safe fix for Reno because we cannot safely force push changes to the Git history. We couldn't find a way to teach Reno which release notes correspond to which version because it tries automating this all via Git.

Switching to Towncrier

Towncrier is a popular release notes generator in the Python community used by projects like pip and pytest.

It is much simpler than Reno because it is less magical: it doesn't even look at Git. Instead, Towncrier has a simple workflow:

• Until a release, each change has a dedicated release note file describing it.
• When preparing a release note, you manually run towncrier build and it will combine all the separate release notes together and add them to an aggregated release note file for the entire release, like 0.20.0.rst. It will also delete the individual release note files since they are now moved into the aggregated file.

Unlike Reno, this means that you only have standalone release notes files for unreleased versions. If you want to make changes to prior release notes, you simplify modify the aggregated file for that release, like changing 0.20.0.rst.

This means there is a new step to preparing releases: you have to first create a PR to prep the release notes.

Why do we have one release note file per release?

By default, towncrier writes every release note to a single file like CHANGES.rst. We instead have one file per release, like 0.20.0.rst. We do this because it makes patch releases like 0.20.1 simpler; when we do a patch release, we need to cherry-pick the release prep from the stable/x branch back into main so that the release note file for 0.20.1 shows up on main. By having the release notes be separated files per release, we avoid that cherry-pick from having a merge conflict with main.

We have a helper script that Tox and Make call to concatenate all these separate release note files into a single release_notes.rst to be used by the Sphin build.

[coveralls]

Pull Request Test Coverage Report for Build 8285402559

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 82.297%

---

Totals
Change from base Build 8269393108:	0.0%
Covered Lines:	5769
Relevant Lines:	7010

---

💛 - Coveralls

[kt474]

LGTM! Thank you!