Release process improvements

[hu55a1n1]

Ways to improve our release process described in CONTRIBUTING.md

1. Update the changelog to reflect and summarize all changes in the release. This involves:

• Running unclog build -u and copy pasting the output at the top of the CHANGELOG.md file, making sure to update the header with the new version.
• Running unclog release vX.Y.Z to create a summary of all of the changes in this release.
• Committing the updated CHANGELOG.md file and .changelog directory to the repo.

2. Push this to a branch release/vX.Y.Z according to the version number of the anticipated release (e.g. release/v0.17.0) and open a draft PR.

• Both these steps can be readily automated using a GitHub workflow. Apalache's prepare-release workflow is very similar to what we would want. Note - A personal API token is required to authenticate the API call that opens the PR.
• The workflow can also be scheduled to run periodically (i.e. once every 2 weeks, etc.).
• Reviewers must ensure that PR changelog entries are well-formed before being merged. (Might be a good addition to the PR template checklist)
• The created release PR must be reviewed/merged for the release process to continue.
• We could add a special PR template for releases that includes a comprehensive checklist of all things that need to be addressed/reviewed in a release PR. The automatically created release PR should use this template.

3. Bump all relevant versions in the codebase to the new version and push these changes to the release PR. This includes:
   All Cargo.toml files (making sure dependencies' versions are updated too).
   All crates' lib.rs files documentation references' html_root_url parameters must point to the new version.
   Every reference to Hermes version in the guide.
   Important: The ibc-proto crate version must only be bumped if it has changed since the last release. All other crates are bumped together.

• One way to automate this would be to have a version file in the project root which is the only place containing the actual version(s).
• All occurrences of versions in the project must be replaced with placeholders such as {{version-ibc}}.
• A script could then be used to replace all occurrences of the placeholders with the actual version. If we decide to go this route, we could include this step in the prepare-release workflow as well.
  Note that the script cannot know the next version by itself, but if the version file is updated on every merge, it can simply use this.

4. Run cargo doc --all-features --open locally to double-check that all the documentation compiles and seems up-to-date and coherent. Fix any potential issues here and push them to the release PR.

• This could possibly be a CI job that runs once the release PR is submitted.

5. Mark the PR as Ready for Review and incorporate feedback on the release.

• This is where manual intervention is required and reviewers can propose/make changes at this point.

6. Once approved, merge the PR.

• Note that if the release PR isn't merged, the process just stops here.

7. Pull master and run the release.sh script. If any problem arises, submit a new PR, get it merged to master and try again. The reason for not releasing straight from the release branch, and therefore losing the ability to fix publishing problems as they arise, is that we would like the embedded metadata of the published crates, namely the Git commit at which the release was done, to match the Git commit on the master branch which will be tagged. See this article for a more in-depth explanation.
   Note: This step requires the appropriate privileges to push crates to crates.io.

• I think this can be automated using a workflow that is triggered on the merge of the release PR, but we will have to account for partial failures during releases.
• Alternatively, we can trigger cargo publish dry-runs for all crates and leave the actual publishing up to devs.
• If we choose to do this manually, @romac already has a release.sh that doesn't do the dry-runs and can save us some time.

8. Once all crates have been successfully released, create a signed tag and push it to GitHub: git tag -s -a vX.Y.Z. In the tag message, write the version and the link to the corresponding section of the changelog.

9. Once the tag is pushed, wait for the CI bot to create a GitHub release, and update the release description to 📖 CHANGELOG.

10. Wait an hour or so, and check that the CI job has uploaded the Hermes binaries to the release.

• Not sure, but I think there should be a GitHub API to help automate this as well.

Raw Notes/Questions

• What else can be automated?
• automate post unclog build steps
• make sure unclog entries are well-formed before merge
• stricter use of template checklist
• deciding on version number bump? version file?
• pull request template for release PR.
• long standing branch per version? Easier to backport bugfixes?
• Manual bumping of versions! How to automate/test this? Placeholder for version updated by script?
• Release strategy?
• Do we want to have timely releases?
• Will we have long-term-support (LTS) versions? Backport bugfixes? Hotfixes?
• Support multiple SDK/IBC versions? How?
• Match release cycle of ibc-go or SDK?
• Branching model? Branches? Stable, beta, master?
• gitflow v/s Trunk based development?

Resources

• Apalache's GitHub workflows - many of these ideas are inspired by Apalache's release process. Many thanks to @shonfeder's awesome work there!
• Rust's release process
• GitFlow

[shonfeder]

I can also recommend taking a look at https://trunkbaseddevelopment.com/ afaik, it’s much simpler than gitflow, and I’ve generally found it to be a quite pleasant model, that we just don’t have to think about much.