|
| 1 | +# Releases |
| 2 | + |
| 3 | +Tendermint uses [semantic versioning](https://semver.org/) with each release following |
| 4 | +a `vX.Y.Z` format. The `master` branch is used for active development and thus it's |
| 5 | +advisable not to build against it. |
| 6 | + |
| 7 | +The latest changes are always initially merged into `master`. |
| 8 | +Releases are specified using tags and are built from long-lived "backport" branches |
| 9 | +that are cut from `master` when the release process begins. |
| 10 | +Each release "line" (e.g. 0.34 or 0.33) has its own long-lived backport branch, |
| 11 | +and the backport branches have names like `v0.34.x` or `v0.33.x` |
| 12 | +(literally, `x`; it is not a placeholder in this case). Tendermint only |
| 13 | +maintains the last two releases at a time (the oldest release is predominantly |
| 14 | +just security patches). |
| 15 | + |
| 16 | +## Backporting |
| 17 | + |
| 18 | +As non-breaking changes land on `master`, they should also be backported |
| 19 | +to these backport branches. |
| 20 | + |
| 21 | +We use Mergify's [backport feature](https://mergify.io/features/backports) to automatically backport |
| 22 | +to the needed branch. There should be a label for any backport branch that you'll be targeting. |
| 23 | +To notify the bot to backport a pull request, mark the pull request with the label corresponding |
| 24 | +to the correct backport branch. For example, to backport to v0.35.x, add the label `S:backport-to-v0.35.x`. |
| 25 | +Once the original pull request is merged, the bot will try to cherry-pick the pull request |
| 26 | +to the backport branch. If the bot fails to backport, it will open a pull request. |
| 27 | +The author of the original pull request is responsible for solving the conflicts and |
| 28 | +merging the pull request. |
| 29 | + |
| 30 | +### Creating a backport branch |
| 31 | + |
| 32 | +If this is the first release candidate for a major release, you get to have the honor of creating |
| 33 | +the backport branch! |
| 34 | + |
| 35 | +Note that, after creating the backport branch, you'll also need to update the |
| 36 | +tags on `master` so that `go mod` is able to order the branches correctly. You |
| 37 | +should tag `master` with a "dev" tag that is "greater than" the backport |
| 38 | +branches tags. See [#6072](https://github.com/tendermint/tendermint/pull/6072) |
| 39 | +for more context. |
| 40 | + |
| 41 | +In the following example, we'll assume that we're making a backport branch for |
| 42 | +the 0.35.x line. |
| 43 | + |
| 44 | +1. Start on `master` |
| 45 | +2. Create and push the backport branch: |
| 46 | + `git checkout -b v0.35.x; git push origin v0.35.x` |
| 47 | +3. Go back to master and tag it as the dev branch for the _next_ major release and push it back up: |
| 48 | + `git tag -a v0.36.0-dev -m "Development base for Tendermint v0.36."; git push origin v0.36.0-dev` |
| 49 | +4. Create a new workflow (still on master) to run e2e nightlies for the new backport branch. |
| 50 | + (See https://github.com/tendermint/tendermint/blob/master/.github/workflows/e2e-nightly-master.yml |
| 51 | + for an example.) |
| 52 | +5. Add a new section to the Mergify config (`.github/mergify.yml`) to enable the |
| 53 | + backport bot to work on this branch, and add a corresponding `S:backport-to-v0.35.x` |
| 54 | + [label](https://github.com/tendermint/tendermint/labels) so the bot can be triggered. |
| 55 | + |
| 56 | +## Release candidates |
| 57 | + |
| 58 | +Before creating an official release, especially a major release, we may want to create a |
| 59 | +release candidate (RC) for our friends and partners to test out. We use git tags to |
| 60 | +create RCs, and we build them off of backport branches. |
| 61 | + |
| 62 | +Tags for RCs should follow the "standard" release naming conventions, with `-rcX` at the end |
| 63 | +(for example, `v0.35.0-rc0`). |
| 64 | + |
| 65 | +(Note that branches and tags _cannot_ have the same names, so it's important that these branches |
| 66 | +have distinct names from the tags/release names.) |
| 67 | + |
| 68 | +If this is the first RC for a major release, you'll have to make a new backport branch (see above). |
| 69 | +Otherwise: |
| 70 | + |
| 71 | +1. Start from the backport branch (e.g. `v0.35.x`). |
| 72 | +2. Run the integration tests and the e2e nightlies |
| 73 | + (which can be triggered from the Github UI; |
| 74 | + e.g., https://github.com/tendermint/tendermint/actions/workflows/e2e-nightly-34x.yml). |
| 75 | +3. Prepare the changelog: |
| 76 | + - Move the changes included in `CHANGELOG_PENDING.md` into `CHANGELOG.md`. Each RC should have |
| 77 | + it's own changelog section. These will be squashed when the final candidate is released. |
| 78 | + - Run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for |
| 79 | + all PRs |
| 80 | + - Ensure that `UPGRADING.md` is up-to-date and includes notes on any breaking changes |
| 81 | + or other upgrading flows. |
| 82 | + - Bump TMVersionDefault version in `version.go` |
| 83 | + - Bump P2P and block protocol versions in `version.go`, if necessary. |
| 84 | + Check the changelog for breaking changes in these components. |
| 85 | + - Bump ABCI protocol version in `version.go`, if necessary |
| 86 | +4. Open a PR with these changes against the backport branch. |
| 87 | +5. Once these changes have landed on the backport branch, be sure to pull them back down locally. |
| 88 | +6. Once you have the changes locally, create the new tag, specifying a name and a tag "message": |
| 89 | + `git tag -a v0.35.0-rc0 -m "Release Candidate v0.35.0-rc0` |
| 90 | +7. Push the tag back up to origin: |
| 91 | + `git push origin v0.35.0-rc0` |
| 92 | + Now the tag should be available on the repo's releases page. |
| 93 | +8. Future RCs will continue to be built off of this branch. |
| 94 | + |
| 95 | +Note that this process should only be used for "true" RCs-- |
| 96 | +release candidates that, if successful, will be the next release. |
| 97 | +For more experimental "RCs," create a new, short-lived branch and tag that instead. |
| 98 | + |
| 99 | +## Major release |
| 100 | + |
| 101 | +This major release process assumes that this release was preceded by release candidates. |
| 102 | +If there were no release candidates, begin by creating a backport branch, as described above. |
| 103 | + |
| 104 | +1. Start on the backport branch (e.g. `v0.35.x`) |
| 105 | +2. Run integration tests (`make test_integrations`) and the e2e nightlies. |
| 106 | +3. Prepare the release: |
| 107 | + - "Squash" changes from the changelog entries for the RCs into a single entry, |
| 108 | + and add all changes included in `CHANGELOG_PENDING.md`. |
| 109 | + (Squashing includes both combining all entries, as well as removing or simplifying |
| 110 | + any intra-RC changes. It may also help to alphabetize the entries by package name.) |
| 111 | + - Run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for |
| 112 | + all PRs |
| 113 | + - Ensure that `UPGRADING.md` is up-to-date and includes notes on any breaking changes |
| 114 | + or other upgrading flows. |
| 115 | + - Bump TMVersionDefault version in `version.go` |
| 116 | + - Bump P2P and block protocol versions in `version.go`, if necessary |
| 117 | + - Bump ABCI protocol version in `version.go`, if necessary |
| 118 | +4. Open a PR with these changes against the backport branch. |
| 119 | +5. Once these changes are on the backport branch, push a tag with prepared release details. |
| 120 | + This will trigger the actual release `v0.35.0`. |
| 121 | + - `git tag -a v0.35.0 -m 'Release v0.35.0'` |
| 122 | + - `git push origin v0.35.0` |
| 123 | +6. Make sure that `master` is updated with the latest `CHANGELOG.md`, `CHANGELOG_PENDING.md`, and `UPGRADING.md`. |
| 124 | +7. Add the release to the documentation site generator config (see |
| 125 | + [DOCS_README.md](./docs/DOCS_README.md) for more details). In summary: |
| 126 | + - Start on branch `master`. |
| 127 | + - Add a new line at the bottom of [`docs/versions`](./docs/versions) to |
| 128 | + ensure the newest release is the default for the landing page. |
| 129 | + - Add a new entry to `themeConfig.versions` in |
| 130 | + [`docs/.vuepress/config.js`](./docs/.vuepress/config.js) to include the |
| 131 | + release in the dropdown versions menu. |
| 132 | + |
| 133 | +## Minor release (point releases) |
| 134 | + |
| 135 | +Minor releases are done differently from major releases: They are built off of |
| 136 | +long-lived backport branches, rather than from master. As non-breaking changes |
| 137 | +land on `master`, they should also be backported into these backport branches. |
| 138 | + |
| 139 | +Minor releases don't have release candidates by default, although any tricky |
| 140 | +changes may merit a release candidate. |
| 141 | + |
| 142 | +To create a minor release: |
| 143 | + |
| 144 | +1. Checkout the long-lived backport branch: `git checkout v0.35.x` |
| 145 | +2. Run integration tests (`make test_integrations`) and the nightlies. |
| 146 | +3. Check out a new branch and prepare the release: |
| 147 | + - Copy `CHANGELOG_PENDING.md` to top of `CHANGELOG.md` |
| 148 | + - Run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for all issues |
| 149 | + - Run `bash ./scripts/authors.sh` to get a list of authors since the latest release, and add the GitHub aliases of external contributors to the top of the CHANGELOG. To lookup an alias from an email, try `bash ./scripts/authors.sh <email>` |
| 150 | + - Reset the `CHANGELOG_PENDING.md` |
| 151 | + - Bump the TMDefaultVersion in `version.go` |
| 152 | + - Bump the ABCI version number, if necessary. |
| 153 | + (Note that ABCI follows semver, and that ABCI versions are the only versions |
| 154 | + which can change during minor releases, and only field additions are valid minor changes.) |
| 155 | +4. Open a PR with these changes that will land them back on `v0.35.x` |
| 156 | +5. Once this change has landed on the backport branch, make sure to pull it locally, then push a tag. |
| 157 | + - `git tag -a v0.35.1 -m 'Release v0.35.1'` |
| 158 | + - `git push origin v0.35.1` |
| 159 | +6. Create a pull request back to master with the CHANGELOG & version changes from the latest release. |
| 160 | + - Remove all `R:minor` labels from the pull requests that were included in the release. |
| 161 | + - Do not merge the backport branch into master. |
0 commit comments