---
# System prepended metadata

title: Prysm Git Flow Strategy Proposal

---

# 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`

![linux kernel release tracks](https://i.imgur.com/PjPjvzk.png)

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

![Image](https://jeffkreeftmeijer.com/git-flow/git-flow.png)

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
- We begin a release candidate branch from the `develop` branch once appropriate
    - Release candidate branches should be named v1.0.3.rc, for example
    - Release candidate branches only have bug fixes applied to them
    - Bug fixes from release candidate branches can be continuously merged back into `develop`
    - Once a release branch is complete and canary tested, we merge into master and tag
    - We shoud not create release branches preemptively. They should only be created from `develop` once we are ready to work on them
- 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, release candidate branches are relatively "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
