Cherrypick Towncrier PR into stable/0.21 for patch release #1529
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
## 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. Qiskit#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](https://medium.com/opsops/software-discovery-reno-b072827ad883) > 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](https://towncrier.readthedocs.io/en/stable/) 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.
Pull Request Test Coverage Report for Build 8330759191Details
💛 - Coveralls |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Details and comments
Fixes #