From ec2323c1eed10003f75440a5eded0792e92edd1d Mon Sep 17 00:00:00 2001 From: MSalopek Date: Fri, 9 Jun 2023 10:08:59 +0200 Subject: [PATCH] chore: add goreleaser, cleanup release process (#2549) * chore: add goreleaser, cleanup release process * chore: update RELEASING.md * chore: add RELEASE_NOTES.md; add make create-release * chore: rm old release file * update release process * fix: apply review comments * chore: update RELEASE_PROCESS.md with PR comments * chore: add install step for goreleaser dry-run --------- Co-authored-by: mpoke --- .github/workflows/release.yml | 126 ++++++----------------- .goreleaser.yml | 32 +++--- CONTRIBUTING.md | 8 +- Makefile | 45 ++++++-- RELEASE_NOTES.md | 32 ++++++ RELEASE_PROCESS.md | 189 ++++++++++++++++++++++++++++++++++ RELEASING.md | 182 -------------------------------- UPGRADING.md | 5 + 8 files changed, 308 insertions(+), 311 deletions(-) create mode 100644 RELEASE_NOTES.md create mode 100644 RELEASE_PROCESS.md delete mode 100644 RELEASING.md create mode 100644 UPGRADING.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index adf1fd1c4cb..9361d207cc7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,100 +1,34 @@ -name: create release +name: "Release" on: - push: - tags: - - "v[0-9]+\\.[0-9]+\\.[0-9]+" - - "v[0-9]+\\.[0-9]+\\.[0-9]+-rc[0-9]+" + # can be used to re-release an existing tag + workflow_dispatch: + + push: + tags: + - "v[0-9]+\\.[0-9]+\\.[0-9]+" + - "v[0-9]+\\.[0-9]+\\.[0-9]+-rc[0-9]+" jobs: - build: - name: Create Release - runs-on: ubuntu-latest - steps: - - name: Checkout code - uses: actions/checkout@v3.5.2 - - name: set tag env - run: echo "VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV - - name: install go - uses: actions/setup-go@v4 - with: - go-version: 1.20.x - check-latest: true - - name: Build Artifacts - run: make distclean build-reproducible - - name: generate release note - run: go run ./contrib/generate_release_note/main.go ${{ env.VERSION }} ./artifacts/build_report ./CHANGELOG.md - - name: Create Release - id: create_release - uses: actions/create-release@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - with: - tag_name: ${{ github.ref }} - release_name: Release ${{ github.ref }} - body_path: ./releasenote - draft: true - prerelease: false - - name: Upload build_report - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ github.token }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./artifacts/build_report - asset_name: build_report - asset_content_type: application/file - - name: Upload darwin-amd64 artifact - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ github.token }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./artifacts/gaiad-${{ env.VERSION }}-darwin-amd64 - asset_name: gaiad-${{ env.VERSION }}-darwin-amd64 - asset_content_type: application/binary - - name: Upload darwin-arm64 artifact - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ github.token }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./artifacts/gaiad-${{ env.VERSION }}-darwin-arm64 - asset_name: gaiad-${{ env.VERSION }}-darwin-arm64 - asset_content_type: application/binary - - name: Upload linux-amd64 artifact - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ github.token }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./artifacts/gaiad-${{ env.VERSION }}-linux-amd64 - asset_name: gaiad-${{ env.VERSION }}-linux-amd64 - asset_content_type: application/binary - - name: Upload linux-arm64 artifact - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ github.token }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./artifacts/gaiad-${{ env.VERSION }}-linux-arm64 - asset_name: gaiad-${{ env.VERSION }}-linux-arm64 - asset_content_type: application/binary - - name: Upload windows-amd64 artifact - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ github.token }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./artifacts/gaiad-${{ env.VERSION }}-windows-amd64.exe - asset_name: gaiad-${{ env.VERSION }}-windows-amd64.exe - asset_content_type: application/binary - - name: Upload compression - uses: actions/upload-release-asset@v1 - env: - GITHUB_TOKEN: ${{ github.token }} - with: - upload_url: ${{ steps.create_release.outputs.upload_url }} - asset_path: ./artifacts/gaiad-${{ env.VERSION }}.tar.gz - asset_name: gaiad-${{ env.RELEASE_VERSION }}.tar.gz - asset_content_type: application/gzip + release: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - uses: actions/setup-go@v4 + with: + go-version: "1.20" + + - name: Set Env + run: echo "TM_VERSION=$(go list -m github.com/tendermint/tendermint | sed 's:.* ::')" >> $GITHUB_ENV + + - name: Release + uses: goreleaser/goreleaser-action@v4 + with: + version: latest + args: release --clean --release-notes ./RELEASE_NOTES.md + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.goreleaser.yml b/.goreleaser.yml index 6d204956745..16e6b85ed1f 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -4,10 +4,6 @@ project_name: gaia env: - GO111MODULE=on -before: - hooks: - - go mod tidy -compat=1.20 - builds: - main: ./cmd/gaiad id: "gaiad" @@ -19,6 +15,7 @@ builds: env: - CGO_ENABLED=0 ldflags: + # .Env.TM_VERSION is provided in the workflow runner environment -> see .github/workflows/release.yml - -s -w -X main.commit={{.Commit}} -X main.date={{ .CommitDate }} -X github.com/cosmos/cosmos-sdk/version.Name=gaia -X github.com/cosmos/cosmos-sdk/version.AppName=gaiad -X github.com/cosmos/cosmos-sdk/version.Version={{ .Version }} -X github.com/cosmos/cosmos-sdk/version.Commit={{ .Commit }} -X github.com/cosmos/cosmos-sdk/version.BuildTags=netgo,ledger -X github.com/tendermint/tendermint/version.TMCoreSemVer={{ .Env.TM_VERSION }} goos: - darwin @@ -29,20 +26,23 @@ builds: - arm64 archives: - - format: tar.gz - wrap_in_directory: "true" - format_overrides: - - goos: windows - format: zip + # disables archiving; to enable use commented lines below + - format: binary name_template: "{{ .Binary }}-v{{ .Version }}-{{ .Os }}-{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}" - files: - - LICENSE - - README.md + + # - format: tar.gz + # wrap_in_directory: "true" + # format_overrides: + # - goos: windows + # format: zip + # name_template: "{{ .Binary }}-v{{ .Version }}-{{ .Os }}-{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}" + # files: + # - LICENSE + # - README.md + # rlcp: true release: - github: - owner: cosmos - name: gaia + prerelease: true name_template: "v{{.Version}}" checksum: @@ -53,4 +53,4 @@ snapshot: name_template: SNAPSHOT-{{ .Commit }} changelog: - skip: true + skip: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63a8c2405be..6d12e0d4583 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ - [Contributing](#contributing) - [Overview](#overview) - - [Stewarding team responsibility](#stewarding-team-responsibility) + - [Responsibilities of the stewarding team](#responsibilities-of-the-stewarding-team) - [Ease of reviewing](#ease-of-reviewing) - [Workflow](#workflow) - [Project Board](#project-board) @@ -249,11 +249,7 @@ To generate the protobuf stubs, you can run `make proto-gen`. User-facing repos should adhere to the trunk based development branching model: https://trunkbaseddevelopment.com. User branches should start with a user name, example: `{moniker}/{issue#}-branch-name`. -Gaia follows [semantic versioning](https://semver.org), but with the following deviations to account for state-machine and API breaking changes: - -- State-machine breaking changes will result in an increase of the major version X (X.y.z). -- API breaking changes will result in an increase of the minor version Y (x.Y.z | x > 0). -- All other changes will result in an increase of the patch version Z (x.y.Z | x > 0). +Gaia follows [semantic versioning](https://semver.org), but with the some deviations to account for state-machine and API breaking changes. See [RELEASE_PROCESS.md](./RELEASE_PROCESS.md) for details. ### PR Targeting diff --git a/Makefile b/Makefile index 6221a9b9462..152e591ab0f 100644 --- a/Makefile +++ b/Makefile @@ -115,17 +115,6 @@ vulncheck: $(BUILDDIR)/ GOBIN=$(BUILDDIR) go install golang.org/x/vuln/cmd/govulncheck@latest $(BUILDDIR)/govulncheck ./... -build-reproducible: go.sum - $(DOCKER) rm latest-build || true - $(DOCKER) run --volume=$(CURDIR):/sources:ro \ - --env TARGET_PLATFORMS='linux/amd64 darwin/amd64 linux/arm64 darwin/arm64 windows/amd64' \ - --env APP=gaiad \ - --env VERSION=$(VERSION) \ - --env COMMIT=$(COMMIT) \ - --env LEDGER_ENABLED=$(LEDGER_ENABLED) \ - --name latest-build majita/rbuilder:latest - $(DOCKER) cp -a latest-build:/home/builder/artifacts/ $(CURDIR)/ - build-linux: go.sum LEDGER_ENABLED=false GOOS=linux GOARCH=amd64 $(MAKE) build @@ -148,6 +137,40 @@ clean: distclean: clean rm -rf vendor/ +############################################################################### +### Release ### +############################################################################### + +# create tag and run goreleaser without publishing +create-release-dry-run: +ifneq ($(strip $(TAG)),) + @echo "--> Dry running release for tag: $(TAG)" + @echo "--> Create tag: $(TAG) dry run" + git tag -s $(TAG) -m $(TAG) + git push origin $(TAG) --dry-run + @echo "--> Delete local tag: $(TAG)" + @git tag -d $(TAG) + @echo "--> Running goreleaser" + @go install github.com/goreleaser/goreleaser@latest + TM_VERSION=$(TM_VERSION) goreleaser release --snapshot --clean + @rm -rf dist/ + @echo "--> Done create-release-dry-run for tag: $(TAG)" +else + @echo "--> No tag specified, skipping tag release" +endif + +# create tag and publish it +create-release: +ifneq ($(strip $(TAG)),) + @echo "--> Running release for tag: $(TAG)" + @echo "--> Create release tag: $(TAG)" + git tag -s $(TAG) -m $(TAG) + git push origin $(TAG) + @echo "--> Done creating release tag: $(TAG)" +else + @echo "--> No tag specified, skipping create-release" +endif + ############################################################################### ### Devdoc ### ############################################################################### diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md new file mode 100644 index 00000000000..12b4ee9e1f4 --- /dev/null +++ b/RELEASE_NOTES.md @@ -0,0 +1,32 @@ + + +# Gaia Release Notes + +## 📝 Changelog + +Check out the [changelog](https://github.com/cosmos/gaia/blob//CHANGELOG.md) for a list of relevant changes or [compare all changes](https://github.com/cosmos/cosmos-sdk/compare/release/...) from last release. + + +Refer to the [upgrading guide](https://github.com/cosmos/cosmos-sdk/blob/release//UPGRADING.md) when migrating from `` to ``. + +## 🚀 Highlights + + + +## 🔨 Build from source + +```bash +git clone https://github.com/cosmos/gaia +cd gaia && git checkout +make install +``` + +## ⚡️ Download binaries + +Binaries for linux, darwin, and windows are available below. \ No newline at end of file diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md new file mode 100644 index 00000000000..c9317343d6a --- /dev/null +++ b/RELEASE_PROCESS.md @@ -0,0 +1,189 @@ +# Release Process + +- [Release Process](#release-process) + - [Major Release Procedure](#major-release-procedure) + - [Changelog](#changelog) + - [Release Notes](#release-notes) + - [Tagging Procedure](#tagging-procedure) + - [Test building artifacts](#test-building-artifacts) + - [Installing goreleaser](#installing-goreleaser) + - [Non-major Release Procedure](#non-major-release-procedure) + - [Major Release Maintenance](#major-release-maintenance) + - [Stable Release Policy](#stable-release-policy) + + +This document outlines the release process for Cosmos Hub (Gaia). + +Gaia follows [semantic versioning](https://semver.org), but with the following deviations to account for state-machine and API breaking changes: + +- State-machine breaking changes will result in an increase of the major version X (X.y.z). +- Emergency releases & API breaking changes (changes in node interactions e.g. queries) will result in an increase of the minor version Y (x.Y.z | x > 0). +- All other changes will result in an increase of the patch version Z (x.y.Z | x > 0). + +**State compatibility**: +It is critical for the patch releases to be state-machine compatible with prior releases in the same minor version. +For example, v9.2.1 must be compatible with v9.2.0. + +Minor releases will be handled on a case-by-case basis, but generally should only arise in case of safety or security issues that require a co-ordinated network upgrade without a governance process. + +This is to ensure determinism, i.e. that given the same input, the nodes will always produce the same output. +State-incompatibility is allowed for major upgrades because all nodes in the network perform it at the same time. +Therefore, after the upgrade, the nodes continue functioning in a deterministic way. + +**Note**: State-machine breaking changes include changes that impact the amount of gas needed to execute a transaction as it results in a different `apphash` after the code is executed. + +## Major Release Procedure + +A _major release_ is an increment of the first number (eg: `v9.1.0` → `v10.0.0`). Each major release opens a _stable release series_ and receives updates outlined in the [Major Release Maintenance](#major-release-maintenance) section. + +**Note**: Generally, PRs should target either `main` or a long-lived feature branch (see [CONTRIBUTING.md](./CONTRIBUTING.md#pull-requests)). +An exception are PRs open via the Github mergify integration (i.e., backported PRs). + +* Once the team feels that `main` is _**feature complete**_, we create a `release/vY` branch (going forward known a release branch), + where `Y` is the version number, with the minor and patch part substituted to `x` (eg: 11.x). + * Update the [GitHub mergify integration](./.mergify.yml) by adding instructions for automatically backporting commits from `main` to the `release/vY` using the `A:backport/vY` label. + * **PRs targeting directly a release branch can be merged _only_ when exceptional circumstances arise**. +* In the release branch + * Create a new version section in the `CHANGELOG.md` + * All links must point to their respective pull request. + * The `CHANGELOG.md` must contain only the changes of that specific released version. + All other changelog entries must be deleted and linked to the `main` branch changelog ([example]([TBA](https://github.com/cosmos/gaia/blob/release/v9.0.x/CHANGELOG.md))). + * Note: `CHANGELOG.md` should not contain release candidate entries. + * Create release notes, in `RELEASE_NOTES.md`, highlighting the new features and changes in the version. + This is needed so the bot knows which entries to add to the release page on GitHub. + * Additionally verify that the `UPGRADING.md` file is up to date and contains all the necessary information for upgrading to the new version. +* We freeze the release branch from receiving any new features and focus on releasing a release candidate. + * Finish audits and reviews. + * Add more tests. + * Fix bugs as they are discovered. +* After the team feels that the release branch works fine (i.e., has `~90%` chance of reaching mainnet), we cut a release candidate. + * Create a new annotated git tag for a release candidate in the release branch (follow the [Tagging Procedure](#tagging-procedure)). + * The release verification on public testnets must pass. + * When bugs are found, create a PR for `main`, and backport fixes to the release branch. + * Create new release candidate tags after bugs are fixed. +* After the team feels the release candidate is mainnet ready, create a full release: + * Update `CHANGELOG.md`. + * Run `make format` to format the code. + * Create a new annotated git tag in the release branch (follow the [Tagging Procedure](#tagging-procedure)). This will trigger the automated release process (which will also create the release artifacts). + * Once the release process completes, modify release notes if needed. + +### Changelog + +You can obtain the changelog by running: +```bash +git log --oneline --decorate .. + +# example +git log --oneline --decorate v9.0.0..v9.1.0 +``` + +### Release Notes + +Release notes will be created using the `RELEASE_NOTES.md` from the release branch. +Once the automated releases process is completed, please add any missing information the the release notes using Github UI. + +With every release, the `goreleaser` tool will create a file with all the build artifact checksums and upload it alongside the artifacts. +The file is called `SHA256SUMS-{{.version}}.txt` and contains the following: +``` +098b00ed78ca01456c388d7f1f22d09a93927d7a234429681071b45d94730a05 gaiad_0.0.4_windows_arm64.exe +15b2b9146d99426a64c19d219234cd0fa725589c7dc84e9d4dc4d531ccc58bec gaiad_0.0.4_darwin_amd64 +604912ee7800055b0a1ac36ed31021d2161d7404cea8db8776287eb512cd67a9 gaiad_0.0.4_darwin_arm64 +76e5ff7751d66807ee85bc5301484d0f0bcc5c90582d4ba1692acefc189392be gaiad_0.0.4_linux_arm64 +bcbca82da2cb2387ad6d24c1f6401b229a9b4752156573327250d37e5cc9bb1c gaiad_0.0.4_windows_amd64.exe +f39552cbfcfb2b06f1bd66fd324af54ac9ee06625cfa652b71eba1869efe8670 gaiad_0.0.4_linux_amd64 +``` + +### Tagging Procedure + +**Important**: _**Always create tags from your local machine**_ since all release tags should be signed and annotated. +Using Github UI will create a `lightweight` tag, so it's possible that `gaiad version` returns a commit hash, instead of a tag. +This is important because most operators build from source, and having incorrect information when you run `make install && gaiad version` raises confusion. + +The following steps are the default for tagging a specific branch commit using git on your local machine. Usually, release branches are labeled `release/v*`: + +Ensure you have checked out the commit you wish to tag and then do: +```bash +git pull --tags + +# test tag creation and releasing using goreleaser +make create-release-dry-run TAG=v11.0.0 + +# after successful test push the tag +make create-release TAG=v11.0.0 +``` + +To re-create a tag: +```bash +# delete a tag locally +git tag -d v11.0.0 + +# push the deletion to the remote +git push --delete origin v11.0.0 + +# redo create-release +make create-release-dry-run TAG=v11.0.0 +make create-release TAG=v11.0.0 +``` + +#### Test building artifacts + +Before tagging a new version, please test the building releasing artifacts by running: + +```bash +TM_VERSION=$(go list -m github.com/tendermint/tendermint | sed 's:.* ::') goreleaser release --snapshot --clean --debug +``` + +#### Installing goreleaser +Check the instructions for installing goreleaser locally for your platform +* https://goreleaser.com/install/ + + +## Non-major Release Procedure + +A minor release_ is an increment of the _point number_ (eg: `v9.0.0 → v9.1.0`, also called _point release_). +A _patch release_ is an increment of the patch number (eg: `v10.0.0` → `v10.0.1`). + +**Important**: _**Non-major releases must not break consensus.**_ + +Updates to the release branch should come from `main` by backporting PRs +(usually done by automatic cherry pick followed by a PRs to the release branch). +The backports must be marked using `backport/Y` label in PR for main. +It is the PR author's responsibility to fix merge conflicts, update changelog entries, and +ensure CI passes. If a PR originates from an external contributor, a member of the stewarding team assumes +responsibility to perform this process instead of the original author. +Lastly, it is the stewarding team's responsibility to ensure that the PR meets all the Stable Release Update (SRU) criteria. + +Non-major Release must follow the [Stable Release Policy](#stable-release-policy). + +After the release branch has all commits required for the next patch release: + +* Update the [changelog](#changelog) and the [release notes](#release-notes). +* Create a new annotated git tag in the release branch (follow the [Tagging Procedure](#tagging-procedure)). This will trigger the automated release process (which will also create the release artifacts). +* Once the release process completes, modify release notes if needed. + +## Major Release Maintenance + +Major Release series continue to receive bug fixes (released as either a Minor or a Patch Release) until they reach **End Of Life**. +Major Release series is maintained in compliance with the **Stable Release Policy** as described in this document. + +**Note**: Not every Major Release is denoted as stable releases. + +After two major releases, a supported major release will be transitioned to unsupported and will be deemed EOL with no further updates. +For example, `release/v10.x` is deemed EOL once the network upgrades to `release/v12.x`. + +## Stable Release Policy + +Once a Gaia release has been completed and published, updates for it are released under certain circumstances +and must follow the [Non-major Release Procedure](#non-major-release-procedure). + +The intention of the Stable Release Policy is to ensure that all major release series that are not EOL, +are maintained with the following categories of fixes: + +- Tooling improvements (including code formatting, linting, static analysis and updates to testing frameworks) +- Performance enhancements for running archival and synching nodes +- Test and benchmarking suites, ensuring that fixes are sound and there are no performance regressions +- Library updates including point releases for core libraries such as IBC-Go, Cosmos SDK, Tendermint and other dependencies +- General maintenance improvements, that are deemed necessary by the stewarding team, that help align different releases and reduce the workload on the stewarding team +- Security fixes + +Issues that are likely excluded, are any issues that impact operating a block producing network. diff --git a/RELEASING.md b/RELEASING.md deleted file mode 100644 index 6142e34f3f0..00000000000 --- a/RELEASING.md +++ /dev/null @@ -1,182 +0,0 @@ -# Releasing - -This document outlines the release process for . We use [Long-Lived Version Branch Approach](x) on a `main` branch and a `release` branch. - -We follow [Semver](https://semver.org/) in that any patch releases are non-breaking changes. It's important to note, that breaking changes in a Blockchain context include non-determinism. So if a code change is backwards compatible, it may still impact the amount of gas needed to execute an action, which means the change is in fact breaking as it results in a different apphash after the code is executed. It's important for non-breaking changes to be possible to be used on the live network prior to the release. - -Each major release will have a release branch and patch releases will be tagged on this branch. No patched release has its own branch. (This branch strategy only applies to `v7` and later releases.) - -## Long-Lived Version Branch Approach - -In the Gaia repo, there are two categories of long-lived branches: - -### Branch: `main` - -The `main` branch should be targeted for PRs that contain a bug-fix/feature/improvement that will be included for the next release. - -### Branch: `release` - -There are multiple long-lived branches with the `release/` prefix. Each release series follows the format `release/vn.0.x`, e.g. `release/v7.0.x`. The branch `release/vn.0.x` should point to the most updated `vn` release, e.g. `release/v5.0.x` should be the same as `release/v5.0.8` if that's the latest `v5.0` release. - -## Other Branches - -### branches for the next release - -Other feature/fix branches targeting at `main` contain commits preparing for the next release. When the `release-prepare-branch` is ready for next release, add label `A:backport/vn.0.x` to the PR of `release-prepare-branch` against `main`, then the mergifybot will create a new PR of `mergify/bp/release/vn.0.x` against `Release/vn.0.x`. - -### branches for the backport release - -If the feature/fix branches are for a backport release, `main` branch already contains the commits for the next major release `vn`, the feature/fix branch's PR should target at `Release/vn-1` rather than `main`. - -## Release Procedure - -### Checks and tests - -Before merge and release, the following tests checks need to be conducted: - -- check the `replace` line in `go.mod`, check all the versions in `go.mod` are correct. -- run tests and simulations by `make run-tests`. -- test version compatibilities for minor releases. - -### Major and minor Release - -For a new major release `n`, checkout `release/vn.0.x` from `main`. Merge or use mergify to merge the commits to `release/vn.0.x`, and tag the version. -For minor release. Merge or use mergify to merge the commits to `release/vn.0.x`, and tag the version. - -Usually the first release on the `release/vn.0.x` is a release candidate. - -#### example of releasing `v8.0.0-rc0` - -1. checkout `release/v8.0.x` off `main` -1. get the `v8-prepare-branch` ready including CHANGELOG.md, create a PR to merge `v8-prepare-branch` to `main`, label this PR `A:backport/v8.0.x`. -1. after merge `v8-prepare-branch` to `main`, mergifybot will create a new PR of `mergify/bp/release/v8.0.x` to `release/v8.0.x`. Check the PR, and merge this PR. -1. checkout `release/v8.0.x` and tag `v8.0.0-rc0`. - -#### example of releasing `v8.0.0` - -1. get the `v800-prepare-branch` ready including CHANGELOG.md, create a PR to merge `v800-prepare-branch` to `main`, label this PR `A:backport/v8.0.x`. -1. after merge `v800-prepare-branch` to `main`, mergifybot will create a new PR of `mergify/bp/release/v8.0.x` to `release/v8.0.x`. Check the PR, and merge this PR. -1. checkout `release/v8.0.x` and tag `v8.0.0`. - -#### example of releasing `v8.0.1` - -1. get the `v801-prepare-branch`(off `main`) ready including CHANGELOG.md, create a PR to merge `v801-prepare-branch` to `main`, label this PR `A:backport/v8.0.x`. -1. after merge `v801-prepare-branch` to `main`, mergifybot will create a new PR of `mergify/bp/release/v8.0.x` to `release/v8.0.x`. Check the PR, and merge this PR. -1. checkout `release/v8.0.x` and tag `v8.0.1`. - -### backport release - -For a backport release, checkout a new branch from the right release branch, for example, `release/vn-1.0.x`. Commits to this new branch and merge into `release/vn-1.0.x`, tag the backport version from `release/vn-1.0.x`. - -#### example of backport release `v7.0.5` - -assume main branch is at `v8`. - -1. checkout `v705-prepare-branch` off `release/v7.0.x`, get the backport changes ready including CHANGELOG.md on `v705-prepare-branch`. -1. create a PR to merge `v705-prepare-branch` to `release/v7.0.x`, and merge. -1. checkout `release/v7.0.x` tag `v7.0.5`. - -### Test building artifacts - -Before tagging the version, please test the building releasing artifacts by - -```bash -make distclean build-reproducible -``` - -The above command will generate a directory -`gaia/artifacts` with different os and architecture binaries. If the above command runs sucessfully, delete the directory `rm -r gaia/artifacts`. - -### Tagging - -The following steps are the default for tagging a specific branch commit (usually on a branch labeled `release/vX.X.X`): - -1. Ensure you have checked out the commit you wish to tag -1. `git pull --tags --dry-run` -1. `git pull --tags` -1. `git tag -s v3.0.1 -m 'Release v3.0.1'` - 1. optional, add the `-s` tag to create a signed commit using your PGP key (which should be added to github beforehand) -1. `git push --tags --dry-run` -1. `git push --tags` - -To re-create a tag: - -1. `git tag -d v4.0.0` to delete a tag locally -1. `git push --delete origin v4.0.0`, to push the deletion to the remote -1. Proceed with the above steps to create a tag - -To tag and build without a public release (e.g., as part of a timed security release): - -1. Follow the steps above for tagging locally, but do not push the tags to the repository. -1. After adding the tag locally, you can build the binary, e.g., `make build-reproducible`. -1. To finalize the release, push the local tags, create a release based off the newly pushed tag, and attach the binaries. - -### Release notes - -Ensure you run the reproducible build in order to generate sha256 hashes and platform binaries; -these artifacts should be included in the release. - -```bash -make distclean build-reproducible -``` - -This runs the docker image [tendermintdev/rbuilder](https://hub.docker.com/r/tendermintdev/rbuilder) with a copy of the [rbuilder](https://github.com/tendermint/images/tree/master/rbuilder) docker file. - -Then use the following release text template: - -```markdown -# Gaia v4.0.0 Release Notes - -Note, that this specific release will be updated with a newer changelog, and the below hashes and binaries will also be updated. - -This release includes bug fixes for prop29, as well as additional support for IBC and Ledger signing. - -As there is a breaking change from Gaia v3, the Gaia module has been incremented to v4. - -See the [Cosmos SDK v0.41.0 Release](https://github.com/cosmos/cosmos-sdk/releases/tag/v0.41.0) for details. - -```bash -$ make distclean build-reproducible -App: gaiad -Version: 4.0.0 -Commit: 2bb04266266586468271c4ab322367acbf41188f -Files: - 2e801c7424ef67e6d9fc092c2b75c2d3 gaiad-4.0.0-darwin-amd64 - dc21eb861480e0f55af876f271b512fe gaiad-4.0.0-linux-amd64 - bda165f91bc065afb8a445e72be9a868 gaiad-4.0.0-linux-arm64 - c7203d53bd596679b39b6a94d1dbe0dc gaiad-4.0.0-windows-amd64.exe - 81299b602e1760078e03c97813edda60 gaiad-4.0.0.tar.gz -Checksums-Sha256: - de764e52acc31dd98fa49d8d0eef851f3b7b53e4f1d4fbfda2c07b1a8b115b91 gaiad-4.0.0-darwin-amd64 - e5244ccd98a05479cc35753da1bb5b6bd873f6d8ebe6f8c5d112cf4d9e2761b4 gaiad-4.0.0-linux-amd64 - 7b7c4ea3e2de5f228436dcbb177455906239603b11eca1fb1015f33973d7b567 gaiad-4.0.0-linux-arm64 - b418c5f296ee6f946f44da8497af594c6ad0ece2b1da09a93a45d7d1b1457f27 gaiad-4.0.0-windows-amd64.exe - 3895518436b74be8b042d7d0b868a60d03e1656e2556b12132be0f25bcb061ef gaiad-4.0.0.tar.gz -``` - -# Major Release Maintenance - -Major Release series continue to receive bug fixes (released as a Patch Release) until they reach End Of Life. Major Release series are maintained in compliance with the Stable Release Policy as described in this document. Note: not every Major Release is denoted as a stable release. - -Only the following major release series have a stable release status: - -v7 Theta is supported until v9 Lambda. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a stable point-release. - -v6 Vega is supported until v8 Rho. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a stable point-release. - -v5 Delta is supported until v7 Theta. A fairly strict **bugfix-only** rule applies to pull requests that are requested to be included into a stable point-release. - -After two releases, a supported version will be transitioned to unsupported and will be deemed EOL with no further updates. - -# Stable Release Policy - -The intention of the Stable Release Policy is to ensure that all major release series that are not EOL, are maintained with the following categories of fixes: - -- Tooling improvements (including code formatting, linting, static analysis and updates to testing frameworks) -- Performance enhancements for running archival and synching nodes -- Test and benchmarking suites, ensuring that fixes are sound and there are no performance regressions -- Library updates including point releases for core libraries such as IBC-Go, Cosmos SDK, Tendermint and other dependencies -- General maintenance improvements, that are deemed necessary by the stewarding team, that help align different releases and reduce the workload on the stewarding team -- Security fixes - -Issues that are likely excluded, are any issues that impact operating a block producing network. diff --git a/UPGRADING.md b/UPGRADING.md new file mode 100644 index 00000000000..281412b6fc1 --- /dev/null +++ b/UPGRADING.md @@ -0,0 +1,5 @@ +# Upgrading Gaia + +This guide provides instructions for upgrading to specific versions of Gaia. + +## [Unreleased] \ No newline at end of file