github.com/ari-anchor/sei-tendermint@v0.0.0-20230519144642-dc826b7b56bb/RELEASES.md (about) 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 33 honor of creating 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 46 2. Create and push the backport branch: 47 ```sh 48 git checkout -b v0.35.x 49 git push origin v0.35.x 50 ``` 51 52 3. Create a PR to update the documentation directory for the backport branch. 53 54 We only maintain RFC and ADR documents on master, to avoid confusion. 55 In addition, we rewrite Markdown URLs pointing to master to point to the 56 backport branch, so that generated documentation will link to the correct 57 versions of files elsewhere in the repository. For context on the latter, 58 see https://github.com/tendermint/tendermint/issues/7675. 59 60 To prepare the PR: 61 ```sh 62 # Remove the RFC and ADR documents from the backport. 63 # We only maintain these on master to avoid confusion. 64 git rm -r docs/rfc docs/architecture 65 66 # Update absolute links to point to the backport. 67 go run ./scripts/linkpatch -recur -target v0.35.x -skip-path docs/DOCS_README.md,docs/README.md docs 68 69 # Create and push the PR. 70 git checkout -b update-docs-v035x 71 git commit -m "Update docs for v0.35.x backport branch." docs 72 git push -u origin update-docs-v035x 73 ``` 74 75 Be sure to merge this PR before making other changes on the newly-created 76 backport branch. 77 78 After doing these steps, go back to `master` and do the following: 79 80 1. Tag `master` as the dev branch for the _next_ major release and push it up to GitHub. 81 For example: 82 ```sh 83 git tag -a v0.36.0-dev -m "Development base for Tendermint v0.36." 84 git push origin v0.36.0-dev 85 ``` 86 87 2. Create a new workflow to run e2e nightlies for the new backport branch. 88 (See [e2e-nightly-master.yml][e2e] for an example.) 89 90 3. Add a new section to the Mergify config (`.github/mergify.yml`) to enable the 91 backport bot to work on this branch, and add a corresponding `S:backport-to-v0.35.x` 92 [label](https://github.com/tendermint/tendermint/labels) so the bot can be triggered. 93 94 4. Add a new section to the Dependabot config (`.github/dependabot.yml`) to 95 enable automatic update of Go dependencies on this branch. Copy and edit one 96 of the existing branch configurations to set the correct `target-branch`. 97 98 [e2e]: https://github.com/tendermint/tendermint/blob/master/.github/workflows/e2e-nightly-master.yml 99 100 ## Release candidates 101 102 Before creating an official release, especially a major release, we may want to create a 103 release candidate (RC) for our friends and partners to test out. We use git tags to 104 create RCs, and we build them off of backport branches. 105 106 Tags for RCs should follow the "standard" release naming conventions, with `-rcX` at the end 107 (for example, `v0.35.0-rc0`). 108 109 (Note that branches and tags _cannot_ have the same names, so it's important that these branches 110 have distinct names from the tags/release names.) 111 112 If this is the first RC for a major release, you'll have to make a new backport branch (see above). 113 Otherwise: 114 115 1. Start from the backport branch (e.g. `v0.35.x`). 116 2. Run the integration tests and the e2e nightlies 117 (which can be triggered from the Github UI; 118 e.g., https://github.com/tendermint/tendermint/actions/workflows/e2e-nightly-34x.yml). 119 3. Prepare the changelog: 120 - Move the changes included in `CHANGELOG_PENDING.md` into `CHANGELOG.md`. Each RC should have 121 it's own changelog section. These will be squashed when the final candidate is released. 122 - Run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for 123 all PRs 124 - Ensure that `UPGRADING.md` is up-to-date and includes notes on any breaking changes 125 or other upgrading flows. 126 - Bump TMVersionDefault version in `version.go` 127 - Bump P2P and block protocol versions in `version.go`, if necessary. 128 Check the changelog for breaking changes in these components. 129 - Bump ABCI protocol version in `version.go`, if necessary 130 4. Open a PR with these changes against the backport branch. 131 5. Once these changes have landed on the backport branch, be sure to pull them back down locally. 132 6. Once you have the changes locally, create the new tag, specifying a name and a tag "message": 133 `git tag -a v0.35.0-rc0 -m "Release Candidate v0.35.0-rc0` 134 7. Push the tag back up to origin: 135 `git push origin v0.35.0-rc0` 136 Now the tag should be available on the repo's releases page. 137 8. Future RCs will continue to be built off of this branch. 138 139 Note that this process should only be used for "true" RCs-- 140 release candidates that, if successful, will be the next release. 141 For more experimental "RCs," create a new, short-lived branch and tag that instead. 142 143 ## Major release 144 145 This major release process assumes that this release was preceded by release candidates. 146 If there were no release candidates, begin by creating a backport branch, as described above. 147 148 1. Start on the backport branch (e.g. `v0.35.x`) 149 2. Run integration tests (`make test_integrations`) and the e2e nightlies. 150 3. Prepare the release: 151 - "Squash" changes from the changelog entries for the RCs into a single entry, 152 and add all changes included in `CHANGELOG_PENDING.md`. 153 (Squashing includes both combining all entries, as well as removing or simplifying 154 any intra-RC changes. It may also help to alphabetize the entries by package name.) 155 - Run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for 156 all PRs 157 - Ensure that `UPGRADING.md` is up-to-date and includes notes on any breaking changes 158 or other upgrading flows. 159 - Bump TMVersionDefault version in `version.go` 160 - Bump P2P and block protocol versions in `version.go`, if necessary 161 - Bump ABCI protocol version in `version.go`, if necessary 162 4. Open a PR with these changes against the backport branch. 163 5. Once these changes are on the backport branch, push a tag with prepared release details. 164 This will trigger the actual release `v0.35.0`. 165 - `git tag -a v0.35.0 -m 'Release v0.35.0'` 166 - `git push origin v0.35.0` 167 6. Make sure that `master` is updated with the latest `CHANGELOG.md`, `CHANGELOG_PENDING.md`, and `UPGRADING.md`. 168 7. Add the release to the documentation site generator config (see 169 [DOCS_README.md](./docs/DOCS_README.md) for more details). In summary: 170 - Start on branch `master`. 171 - Add a new line at the bottom of [`docs/versions`](./docs/versions) to 172 ensure the newest release is the default for the landing page. 173 - Add a new entry to `themeConfig.versions` in 174 [`docs/.vuepress/config.js`](./docs/.vuepress/config.js) to include the 175 release in the dropdown versions menu. 176 - Commit these changes to `master` and backport them into the backport 177 branch for this release. 178 179 ## Minor release (point releases) 180 181 Minor releases are done differently from major releases: They are built off of 182 long-lived backport branches, rather than from master. As non-breaking changes 183 land on `master`, they should also be backported into these backport branches. 184 185 Minor releases don't have release candidates by default, although any tricky 186 changes may merit a release candidate. 187 188 To create a minor release: 189 190 1. Checkout the long-lived backport branch: `git checkout v0.35.x` 191 2. Run integration tests (`make test_integrations`) and the nightlies. 192 3. Check out a new branch and prepare the release: 193 - Copy `CHANGELOG_PENDING.md` to top of `CHANGELOG.md` 194 - Run `python ./scripts/linkify_changelog.py CHANGELOG.md` to add links for all issues 195 - 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>` 196 - Reset the `CHANGELOG_PENDING.md` 197 - Bump the TMDefaultVersion in `version.go` 198 - Bump the ABCI version number, if necessary. 199 (Note that ABCI follows semver, and that ABCI versions are the only versions 200 which can change during minor releases, and only field additions are valid minor changes.) 201 4. Open a PR with these changes that will land them back on `v0.35.x` 202 5. Once this change has landed on the backport branch, make sure to pull it locally, then push a tag. 203 - `git tag -a v0.35.1 -m 'Release v0.35.1'` 204 - `git push origin v0.35.1` 205 6. Create a pull request back to master with the CHANGELOG & version changes from the latest release. 206 - Remove all `R:minor` labels from the pull requests that were included in the release. 207 - Do not merge the backport branch into master.