From f45d16f336bf2e7cc42ce4e80356305ebe3c7e57 Mon Sep 17 00:00:00 2001 From: KonradStaniec Date: Mon, 26 Aug 2024 17:23:02 +0200 Subject: [PATCH] Add release process and contributing docs (#27) First step of switching to trunk based development process. Docs are highly influenced by: - https://github.com/cosmos/gaia/blob/main/RELEASE_PROCESS.md - https://github.com/cosmos/gaia/blob/main/CONTRIBUTING.md --- CONTRIBUTING.md | 171 +++++++++++++++++++++++++++++++++++++++++++++ RELEASE_PROCESS.md | 120 +++++++++++++++++++++++++++++++ 2 files changed, 291 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 RELEASE_PROCESS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..7e39d193 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,171 @@ +# Contributing + +- [Contributing](#contributing) + - [Overview](#overview) + - [Pull request rules](#pull-request-rules) + - [Development Procedure](#development-procedure) + - [Testing](#testing) + - [Pull Requests](#pull-requests) + - [Requesting Reviews](#requesting-reviews) + - [Updating Documentation](#updating-documentation) + - [Dependencies](#dependencies) + - [Protobuf](#protobuf) + - [Branching Model and Release](#branching-model-and-release) + - [PR Targeting](#pr-targeting) + +## Overview + +This document codifies rules that must be followed when contributing to +the Babylon node repository. + +### Pull request rules + +Every pull request must be easy to review. To make it possible: + + 1. **Each pull request must do _one thing_**. It must be very clear what that + one thing is when looking at the pull request title, description, and linked + issues. It must also be very clear what value it ultimately aims to deliver, + and for which user(s). + + 2. **Each pull request must be manageable in size**. Self-contained pull + requests that are manageable in size may target `main` directly. Larger + contributions though must be structured as a series of smaller pull requests + each building upon the previous one, all ideally tracked in a tracking issue + These pull requests must target a long-lived feature branch. For details, + see the [development procedure guidelines](#development-procedure). + + **Note**: This does not necessarily apply to documentation-related changes + or automatically generated code (e.g. generated from Protobuf definitions). + But automatically generated code changes should occur within separate + commits, so they are easily distinguishable from manual code changes. + +## Development Procedure + +`main` must be stable, include only completed features and never fail `make +test`, `make test-e2e`, or `make build/install`. + +Depending on the scope of the work, we differentiate between self-contained pull +requests and long-lived contributions (features). + +All pr merges, either to `main` branch or to feature branch must be done by +squash and merge method. + +**Self-contained pull requests**: + +* Fork the repo (core developers must create a branch directly in the Babylon +repo), branch from the HEAD of `main`, make some commits, and submit a PR to +`main`. +* For developers who are core contributors and are working within the Babylon +repo, follow branch name conventions to ensure clear ownership of branches: +`{moniker}/branch-name`. +* See [Branching Model](#branching-model-and-release) for more details. + +**Large contributions**: + +* Make sure that a feature branch is created in the repo or create one. The name + convention for the feature branch must be `feat/branch-name`. Note that + (similar to `main`) all feature branches have branch protection rules and they + run the CI. Unlike `main`, feature branch may intermittently fail `make test`, + `make test-e2e`, or `make build/install`. +* Fork the repo (core developers must create a branch directly in the Babylon + repo), branch from the HEAD of the feature branch, make some commits, and + submit a PR to the feature branch. All PRs targeting a feature branch should + follow the same guidelines in this document. +* Once the feature is completed, submit a PR from the feature branch targeting + `main`. + +### Testing + +Tests can be executed by running `make test` at the top level of the Babylon +repository. Running e2e test can be accomplished by running `make test-e2e` + +### Pull Requests + +Before submitting a pull request: + +* synchronize your branch with the latest base branch (i.e., `main` or feature + branch) and resolve any arising conflicts, e.g., + - either `git fetch origin/main && git merge origin/main` + - or `git fetch origin/main && git rebase -i origin/main` +* run `make test`, `make test-e2e`, `make build/install` to ensure that all + checks and tests pass. + +Then: + +1. If you have something to show, **start with a `Draft` PR**. It's good to have + early validation of your work and we highly recommend this practice. A Draft + PR also indicates to the community that the work is in progress. +2. When the code is complete, change your PR from `Draft` to `Ready for Review`. + +PRs must have a category prefix that is based on the type of changes being made +(for example, `fix`, `feat`, `refactor`, `docs`, and so on). The +[type](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) +must be included in the PR title as a prefix (for example, `fix: +`). This convention ensures that all changes that are committed to +the base branch follow the [Conventional +Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification. + +### Requesting Reviews + +If you would like to receive early feedback on the PR, open the PR as a "Draft" +and leave a comment in the PR indicating that you would like early feedback and +tagging whoever you would like to receive feedback from. + +All PRs require at least two review approvals before they can be merged (one +review might be acceptable in the case of minor changes or changes that do not +affect production code). + +### Updating Documentation + +If you open a PR in Babylon, it is mandatory to update the relevant +documentation in `/docs`. + +## Dependencies + +We use [Go Modules](https://github.com/golang/go/wiki/Modules) to manage +dependency versions. + +The main branch of every Babylon repository should just build with `go get`, +which means they should be kept up-to-date with their dependencies so we can get +away with telling people they can just `go get` our software. + +When dependencies in Babylon `go.mod` are changed, it is generally accepted +practice to delete `go.sum` and then run `go mod tidy`. + +Since some dependencies are not under our control, a third party may break our +build, in which case we can fall back on `go mod tidy -v`. + +## Protobuf + +We use [Protocol Buffers](https://developers.google.com/protocol-buffers) along +with [gogoproto](https://github.com/cosmos/gogoproto) to generate code for use +in Babylon. + +For deterministic behavior around Protobuf tooling, everything is containerized +using Docker. Make sure to have Docker installed on your machine, or head to +[Docker's website](https://docs.docker.com/get-docker/) to install it. + +To generate the protobuf stubs, you can run `make proto-gen`. + +## Branching Model and Release + +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}/branch-name`. + +Babylon 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 + +Ensure that you base and target your PRs on either `main` or a feature branch. + +All complete features and bug fixes must be targeted against `main`. + +Exception is for bug fixes which are only related to a released version. In that +case: +- either, bug fix must be targeted at `main` branch and later back ported to + `release/` branch +- or if `main` and `release/` branched diverged too much, the fix can be +targeted to `release/` branch directly diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md new file mode 100644 index 00000000..29bbfc97 --- /dev/null +++ b/RELEASE_PROCESS.md @@ -0,0 +1,120 @@ +# Release Process + +- [Release Process](#release-process) + - [Breaking Changes](#breaking-changes) + - [Release Procedure](#release-procedure) + - [Creating a new release branch](#creating-a-new-release-branch) + - [Cutting a new release](#cutting-a-new-release) + - [Tagging Procedure](#tagging-procedure) + - [Patch release Procedure](#patch-release-procedure) + +This document outlines the release process for the Babylon node (babylond) + +Babylon follows [semantic versioning](https://semver.org), but with the +following deviations to account for state-machine and API breaking changes. + +- State-machine breaking changes & API breaking changes will result in an +increase of the minor version Y (0.Y.z). +- All other changes will result in an increase of the patch version Z (0.y.Z). + +## Breaking Changes + +A change is considered to be ***state-machine breaking*** if it requires a +coordinated upgrade for the network to preserve state compatibility Note that +when bumping the dependencies of [Cosmos +SDK](https://github.com/cosmos/cosmos-sdk) and +[IBC](https://github.com/cosmos/ibc-go), we will only treat patch releases as +non state-machine breaking. + +A change is considered to be ***API breaking*** if it modifies the provided API. +This includes events, queries, CLI interfaces. + +## Release Procedure + +A _release_ is an increment of the second number (eg: `v0.1.0` → `v0.2.0`) + +**Note**: Generally, PRs should target either `main` or a long-lived feature +branch (see [CONTRIBUTING.md](./CONTRIBUTING.md#pull-requests)). + +* Once the team feels that `main` is _**feature complete**_, we create a + `release/v0.Y.x` branch (going forward known as release branch), where `Y` is + the minor version number, with patch part substituted to `x` (eg: v0.11.x). + * **PRs targeting directly a release branch can be merged _only_ when + exceptional circumstances arise**. +* 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, 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 devnet 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 ready, create a full release: + * **Note:** The final release MUST have the same commit hash as the latest + corresponding release candidate. + * Create a new annotated git tag in the release branch (follow the [Tagging + Procedure](#tagging-procedure)) + +### Creating a new release branch + +- create a new release branch, e.g., `release/v0.10.x` + ```bash + git checkout main + git pull + git checkout -b release/v0.10.x + ``` +- push the release branch upstream + ```bash + git push + ``` +### Cutting a new release + +Before cutting a release (e.g., `v0.10.0-rc.0`), the +following steps are necessary: + +- move to the release branch, e.g., `release/v0.10.x` + ```bash + git checkout release/v0.10.x + ``` +- create new tag (follow the [Tagging Procedure](#tagging-procedure)) + +### 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 `babylond 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 && babylond +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 (assuming +you want to release version `v0.10.0-rc.0` ): +```bash +git pull --tags + +git tag -s -a v0.10.0-rc.0 -m "Version v0.10.0-rc.0" +``` +## Patch Release Procedure + +A _patch release_ is an increment of the patch number (eg: `v10.0.0` → `v10.0.1`). + +**Important**: _**Patch releases can break consensus only in exceptional +circumstances .**_ + +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 and +ensure CI passes. + +After the release branch has all commits required for the next patch release: +* Create a new annotated git tag in the release +branch (follow the [Tagging Procedure](#tagging-procedure)).