Add explanation on how to backport and make patch releases #1074
+67
−0
Conversation
This file contains hidden or 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
palas
requested review from
CarlosLopezDeLara,
Jimbo4350,
carbolymer,
dcoutts,
disassembler,
erikd,
kevinhammond and
newhoggy
as code owners
carbolymer
reviewed
Dec 23, 2025
Contributor
carbolymer
left a comment
carbolymer
left a comment
There was a problem hiding this comment.
Nice. But I think this could be made a bit more concise, without sacrificing the readability of course.
My point is, that this RELEASING.md is quite long already and I've seen people from outside of our team trying to release cardano-api/cardano-cli being discouraged by the amount of words here.
Comment on lines
+198
to
+217
| After identifying the affected versions, we must decide which digit to bump. As with any release, for bug fixes, this is typically the 3rd digit. It may occasionally be the 4th digit if the change is strictly backwards compatible and very minor. | ||
| Using this information, we determine the new version numbers for the patches we will create. | ||
| For example, if we choose to bump the 3rd digit and the affected versions include: | ||
| ``` | ||
| 10.14.1.0, 10.14.0.0, 10.13.0.0, 10.12.2.0, 10.12.1.0, and 10.12.0.0 | ||
| ``` | ||
| We would need to make the following releases (patching the latest version of each series): | ||
| ``` | ||
| 10.14.2.0 (fixes 10.14.1.0) | ||
| 10.13.1.0 (fixes 10.13.0.0) | ||
| 10.12.3.0 (fixes 10.12.2.0) | ||
| ``` | ||
| By doing this, dependencies specifying a version range like `^>= 10.13` will automatically pick up the patched version. |
Contributor
There was a problem hiding this comment.
This feels a bit lengthy, and it rephrases what's in lines 22-26 is described already. I think it would be better to improve the PVP excerpt in lines 22-26 if needed instead.
| ## Backporting | ||
| If a bug affecting a release is discovered long after that release has been made (and potentially after several subsequent releases), it may be necessary to create a patch that fixes each of the affected legacy versions. In this section, we describe how this is done. |
Contributor
There was a problem hiding this comment.
This introduction feels a bit obvious. Personally I'd skip this, but you can leave it if you want.
| The reason we use a PR for the backport is to ensure the changelog gathering script works correctly in later steps. (Alternatively, commits can be added directly to the release branch, but this requires manually writing the changelog entries later.) | ||
| Finally, we merge the PR. This process can be repeated if multiple bugs need to be patched; ideally, create one PR per bug fix. |
Contributor
There was a problem hiding this comment.
Suggested change
| Finally, we merge the PR. This process can be repeated if multiple bugs need to be patched; ideally, create one PR per bug fix. | |
| Finally, we merge the backport PR. This process can be repeated if multiple bugs need to be patched; ideally, create one PR per bug fix. |
| ``` | ||
| We add the generated entry to the `CHANGELOG.md`, bump the version number in the `.cabal` file, and create a release PR. |
Contributor
There was a problem hiding this comment.
Suggested change
| We add the generated entry to the `CHANGELOG.md`, bump the version number in the `.cabal` file, and create a release PR. | |
| We add the generated entry to the `CHANGELOG.md`, bump the version number in the `.cabal` file, and create a release PR targeting `master`. |
Contributor
There was a problem hiding this comment.
I would turn the steps from your changes into numbered list. At least for me it's easier to follow steps in a form of a numbered list rather than text.
| ### 4. Publication to CHaP (Cardano Haskell Packages) | ||
| As usual, we use `add-from-github.sh` to create a CHaP entry for each of our new releases. We open a PR in the CHaP repository, and once the build passes and is approved, we merge it. |
Contributor
There was a problem hiding this comment.
"As usual" might be not clear enough for people not familiar with the release process. Could you add a reference to the exact point above with the command?
Comment on lines
+247
to
+255
| Then, we use `tag.sh` to create a release tag in the repo of the package we are fixing. | ||
| There is one key difference from a standard release workflow: normally, we merge the release PR into `master`. However, for backported patches, we typically do **not** merge the release PR into `master`. Attempting to do so can cause issues: | ||
| - We can't because some of the CI checks don't pass (there may be new requirements that were not satisfied by the old version, or they just broke because the context changed). | ||
| - Even if we can, we may have really complicated conflicts, because the branch we are patching may be really different from the current `master`. | ||
| - Even if we achieve this, through force merging and agressive conflict resolution, we are trying to merge the same patch over and over in `master`, so it does not make a lot of sense. | ||
| Despite all of that, it is possible to do this, and it is a valid option. However, we suggest just closing the release PR and opening a new PR, directly from `master`, that simply updates the change-log for all the release PRs we haven't merged. This can be do just once for all the releases, after all the patches have been release. |
Contributor
There was a problem hiding this comment.
I would rewrite the recommendations with more strong wording. I see this file as a process we have to follow, and not could choose to follow.
Using imperatives would make this a tad shorter.
| Then, we use `tag.sh` to create a release tag in the repo of the package we are fixing. | ||
| There is one key difference from a standard release workflow: normally, we merge the release PR into `master`. However, for backported patches, we typically do **not** merge the release PR into `master`. Attempting to do so can cause issues: |
Contributor
There was a problem hiding this comment.
Suggested change
| There is one key difference from a standard release workflow: normally, we merge the release PR into `master`. However, for backported patches, we typically do **not** merge the release PR into `master`. Attempting to do so can cause issues: | |
| There is one key difference from a standard release workflow: normally, we merge the release PR into `master`. However, for backported patches, we typically do **not** merge the release PR into `master` (assuming the backported fix is already there). Attempting to do so can cause issues: |
or something along those lines
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.
Changelog
Context
We just backported two bug fixes, see #1070. This PR documents the process in case something similar needs to be done again.
How to trust this PR
I guess just reading it and seeing if it makes sense.
Checklist