Investigate alternatives to Reno for Runtime and Provider #979
Comments
kt474
pushed a commit
to kt474/qiskit-ibm-runtime
that referenced
this issue
Mar 18, 2024
## 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.
kt474
added a commit
to Qiskit/qiskit-ibm-runtime
that referenced
this issue
Mar 18, 2024
* Switch from Reno to Towncrier for release notes (#1501) ## 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](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. * remove unreleased change only in main --------- Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
We've been having issues with Reno for Runtime and Provider
Kevin T is open to alternatives. Are there better options like towncrier? This issue is to scope out our requirements then investigate what alternatives exist.
It is not in scope to address Qiskit. They seem happy with Reno. We can ask them if they want to change, but we are not trying to impose any change on them.
The text was updated successfully, but these errors were encountered: