Prysm Git Flow Strategy Proposal

This document outlines a strategy for Prysm's releases and development git flow now that we are in mainnet, describing stable branches, release branches, features, and hot-fixes.

Problems we are trying to solve

• People expect a stable branch, and having a stable master seems like best practice as it would prevent us from having to tell everyone "when you git clone prysm, do not build from master!"
• We need to maintain a high velocity in development, so we need a branch that is always being merged into "develop"
• We want certain PRs to go in as minor patches, while other PRs to go into feature branches
• We want to have release branches
• We want to avoid having huge, stale feature branches that accummulate conflicts every hour and make it impossible for the author to proceed efficiently

Versioning proposal

We propose usage of traditional semver with certain caveats regarding how eth2 works:

Semantic Versioning https://semver.org

Example: Prysm v1.8.14

• Major 1
• Minor features 8
• Patch 14

In terms of eth2 specific changes:

• Any change which requires a hard-fork, or is a phase of eth2 such as sharding will require a major version upgrade
• Features that require design docs and are new behavior or large refactorings in Prysm can go into the minor feature upgrade
• Bug fixes, improvements, optimizations, small features go into patch upgrades

Proposal

(We use everything here except for release branches)

The strategy above defines a traditional git flow model. After some discussion with the team, here is what we have decided on so far:

• master is always stable and has the commit of the latest tagged release
• We create a develop branch which is always being merged into
• Hotfixes branches are used for severe bugs in prod. They are based off master. Once approved, they go into master, then we tag a new release in master
  • Hotfix branches need to be named hotfix/fix-slashing-cache
  • After master is updated from a hotfix, we then manually merge master into develop carefully (needs admin)
• We use feature branches for large scale features, such as refactoring slashing protection. We should not have many feature branches open at the same time (max 1-3). Feature branches need to be named feature/slashing-refactor
  • Feature branches that are not ready for the current release candidate need to wait to be merge into develop until develop is ready to begin the next release candidate

With this setup, releases are "clean", with clear commits coming from develop/feature branches and bug fixes. Release candidates are tested in preproduction soak and are the final barrier before merging into master.

Work estimates

1. Create a develop branch, set default branch for PRs to develop
2. Clean up our old branches
3. Retarget all open PRs to their appropriate branch, create feature branches