This document summarizes internal discussions and puts forth a proposal for managing branching and releases in Codex. This is not set in stone, and can be changed if we find it to be inadequate along the way.

**Rolling development branch.** We will rename `master` to `develop`, and this will become our development branch. PRs should be merged into `develop`. The code in `develop` should always stable enough that it passes tests and integration tests.

**Release branches.** Each release will be forked off of master as a release branch; i.e., `release/katana`. Release branches will be subjected to intensive testing and bugfixing. We must ensure that any critical bug fixes are cherry-picked into `master`. Once a release branch is deemed stable enough, it is released into a testnet.

Because `develop` is allowed to continue evolving, we cannot erase the release branch for as long that release lives. In principle, this means the branch should live, at the very least, all the way to a release being retired from mainnet. In practice, we probably will never erase a release branch as it contains the commit history of that release.

We typically will not support multiple running releases. I therefore expect we will have at most one release running on mainnet, and the one that follows it running on a testnet. On average, therefore, we should have $3$ active branches.

<div style="display: flex; justify-content: center; padding: 10px 0 30px 0">
<img src="https://hackmd.io/_uploads/rk8C0_J1A.png" width="500px"/>
</div>

**Figure 1.** Illustrative example of how branches would work.