-
Notifications
You must be signed in to change notification settings - Fork 543
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'rampup' into limit-zkapp-commands-to-one
- Loading branch information
Showing
9 changed files
with
299 additions
and
198 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,75 @@ | ||
| # Branch management: `compatible` vs `develop` | ||
|
|
||
| The first section describes the reasoning behind the current state of branching, | ||
| and the second section gives you a few tips on how to handle this on a day to | ||
| day basis. | ||
|
|
||
| ## Rationale | ||
|
|
||
| Instead of a single `main` or `master` branch, there are two active branches | ||
| `compatible` and `develop` at all times, where you might want to make changes. | ||
|
|
||
| - `compatible` contains all changes which are literally backwards compatible | ||
| with what people currently run on mainnet. Any nodes running a version of | ||
| mina based off of compatible should connect to current mainnet just fine. | ||
| - `develop` contains changes which break backwards compatibility, or changes | ||
| that depend on past compatibility-breaking changes. “Not backwards | ||
| compatible” means that a daemon running this version of mina will not connect | ||
| to mainnet. | ||
|
|
||
| Major changes to the daemon, protocol, or crypto sometimes will sometimes cause | ||
| backwards-compatibility breaking changes, and of course such changes need to be | ||
| done with deliberation and are not to be taken lightly. Changes to | ||
| infrastructure, auxiliary develop scripts, tests, CI, are usually not be | ||
| backwards compatibility breaking, and thereby should go into compatible (unless | ||
| you are doing something very special and you know what you’re doing). | ||
|
|
||
| On a semi-regular basis, `compatible` gets manually merged into `develop` so | ||
| that — generally speaking — `develop` contains all changes in `compatible.` As | ||
| such, `develop` is a superset of `compatible` i.e. `develop` contains everything | ||
| that `compatible` contains, and more. | ||
|
|
||
| ### Hard fork | ||
|
|
||
| Whenever a hard fork happens, the code in `develop` is released. When this | ||
| happens, the current `compatible` is entirely discarded and a new `compatible` | ||
| gets created based off of `develop` | ||
|
|
||
|  | ||
|
|
||
| ### Releases | ||
|
|
||
| `release/1.X.X` branches are made off of `compatible` and tagged with alpha and | ||
| beta tags until the code is deemed stable, then the `release/1.X.X` branch is | ||
| merged into `master` and given a stable tag. Whenever code is tagged, if | ||
| anything is missing in in the upstream branches (compatible, develop) then the | ||
| tagged branch is also merged back for consistency. | ||
|
|
||
| `release/2.0.0`is the branch where Berkeley QA Net releases are being cut, | ||
| between `compatible`and `develop` in the tree. So far nothing has been tagged | ||
| there but there will be `2.0.0alphaX` tags once the code is more stable and we | ||
| are closer to the Incentivized testnet. | ||
|
|
||
| Unless it is an emergency, code should flow from feature branches | ||
| into `compatible`then in batches into the release branch for tagging and testing | ||
|
|
||
| ## Day to day | ||
|
|
||
| When developing a feature, if it’s not something that breaks compatibility, then | ||
| you should be developing a feature branch, called `foo` for example, based off | ||
| of `compatible`. If you’re not sure whether or not your changes are breaking, | ||
| they probably are not and should build upon compatible. | ||
|
|
||
| There is a CI job called “merges cleanly to develop” which runs whenever you | ||
| have a PR off of `compatible`. If that CI job passes, then you can simply merge | ||
| `foo` into `compatible`. If it does not pass, then when you’re done with your | ||
| changes to `foo` and the PR is all approved, then make a new branch+PR based off | ||
| of your original PR called `foo_DEVELOP` (for example), and then merge | ||
| `develop` into `foo_DEVELOP`. Fix any merge errors that result, then once | ||
| `foo_DEVELOP` is approved, you can merge it into `develop`. Once that’s done, | ||
| the “merges cleanly to develop” CI job in your original `foo` PR should | ||
| automagically start passing when you manually re-run it in CI, in which case you | ||
| can merge. | ||
|
|
||
| If, after making `foo_DEVELOP`, you need to make changes to `foo`, then make | ||
| sure to merge `foo` into `foo_DEVELOP`. In order for the git magic to work, | ||
| `foo_DEVELOP` needs to be a superset of the commits from `foo`, and it also | ||
| needs to merge first. You can make further changes post-merge in `foo_DEVELOP` | ||
| as needed to ensure correctness. | ||
| # Mina Branching Policy | ||
|
|
||
| Mina's current public release is "mainnet", version 1.X. The next hardfork release is "berkeley" 2.0, and the one planned after is "izmir" 3.0. | ||
|
|
||
| The development branches in progress in `mina` are as follows: | ||
| - `master`: current stable release, currently mainnet 1.X. | ||
| - It is frozen from the crypto side, does not depend on `proof-systems`. | ||
| - Never commit to it directly, except to introduce a hotfix. | ||
| - `compatible`: scheduled to be softwork released. | ||
| - The staging branch for mainnet soft fork releases. | ||
| - It contains all the changes which are literally backwards compatible with the current mainnet deployment. Any nodes running a version of mina based off of compatible should connect to the current mainnet. | ||
| - It serves as the preparation ground for the next mainnet soft fork release. | ||
| - `rampup`: what is deployed on the testnet | ||
| - The public incentivized network where an early version of the 2.0 hardfork is deployed for community testing. | ||
| - `rampup` is a temporary branch maintained until public testnets requiring compatibility are running. | ||
| - Never make PRs to `rampup` unless you're explicitly fixing a testnet bug. | ||
| - `berkeley`/`izmir`: next hardfork branch / release candidate. | ||
| - Contains all the new features that are scheduled for the release (berkeley or izmir). | ||
| - `berkeley` is a 2.0 temporary branch maintained until the hard fork after which compatible will include all berkeley changes. | ||
| - The "devnet" testnet is running from `master`, sometimes `compatible`, and features only the current release (not cutting edge/berkeley). | ||
| - `develop`: 2.0 compatible changes not scoped for the 2.0 hard fork upgrade. | ||
| - In other words, `develop` is next non-harmful release (after `berkeley`). | ||
| - Is not *the most cutting edge: might not contain protocol features that scheduled for the subsequent (3.0) release. | ||
| - Contains changes which break backwards compatibility, or changes that depend on past compatibility-breaking changes. “Not backwards compatible” means that a daemon running this version of mina will not connect to mainnet. | ||
| - Major changes to the daemon, protocol, or crypto will sometimes cause backwards-compatibility breaking changes, and of course such changes need to be done with deliberation and are not to be taken lightly. Changes to infrastructure, auxiliary develop scripts, tests, CI, are usually not be backwards compatibility breaking, and thereby should go into compatible (unless you are doing something very special and you know what you’re doing). | ||
| - The difference between `develop` and `berkeley` is that `berkeley` will be the actual hardfork release, while `develop` is subsequent softfork release candidate, softfork after `berkeley`. `develop` is just not tested as rigorously, but it's softfork compatible with `berkeley`. So if `berkeley` can be thought of as 2.0, then `develop` is 2.01. | ||
| - `o1js-main`: compatible with testnet, but has latest `proof-systems` features so that they can be used in `o1js` | ||
| - Contains mina changes from `rampup` | ||
| - But `proof-systems/develop` which by default is used by `mina/develop`. | ||
| - Uses `o1js/main` and `o1js-bindings/main` as explained [here](https://github.com/o1-labs/o1js/blob/main/README-dev.md#branch-compatibility?). | ||
| - When `proof-systems/develop` is too cutting-edge and the adaptations of its changes haven't been landed in mina, `o1js` will use the `proof-systems/o1js-main` branch which is lagging behind `proof-systems/develop` a bit. | ||
|
|
||
|
|
||
| The relationship between the branches is as presented: `master ⊆ compatible ⊆ rampup ⊆ berkeley ⊆ develop`. | ||
| - This means `compatible` includes all the changes in `master`, `rampup` all the changes in `compatible` and so on. So `develop` contains all the changes from *all* the stable branches, but also contains features that do not exist in any of the "subsets". | ||
| - The back-merging direction is thus left-to-right: whenever a feature lands in this chain, it has to be periodically "back-merged" to the right. | ||
| - The branches are merged in the other direction (upstream) only when released. | ||
| - When merely a new feature is introduced, it should aim at the exact target branch. This place depends on the feature, e.g. `compatible` for softfork features, `develop` for more experimental/next release, etc. And then the merged feature is back-propagated downstream (to the right). | ||
|
|
||
|
|
||
|  | ||
|
|
||
|
|
||
|
|
||
| ### Hard forks / releases: | ||
|
|
||
| Whenever a hard fork happens, the code in the corresponding release branch, e.g. `berkeley`, is released to become the new `master`. | ||
| - The intention is then to again have `compatible` as a next soft-fork branch. | ||
| - The transition will be gradual: right after HF, `berkeley` will be copied into both `master` *and* `compatible`, and `develop` will remain as is for a while. PRs from `develop` will be gradually picked based on release scope and included in `compatible` for subsequent soft-fork releases. | ||
| - The pre-Berkeley `compatible` is entirely discarded. The pre-Berkeley branch `berkeley` is completely removed from both `mina` and `proof-systems`. | ||
| - `release/1.X.X` branches are made off of `compatible` and tagged with alpha and beta tags until the code is deemed stable, then the `release/1.X.X` branch is merged into `master` and given a stable tag. Whenever code is tagged, if anything is missing in in the downstream branches (compatible, develop) then the tagged branch is also merged back for consistency. | ||
|
|
||
| ## Day to day: which branch should I use? | ||
|
|
||
| When developing a feature, use the general description of the branches above to decide. Here's a quick rule: | ||
| - If a feature/enhancement/bug fix is not feature breaking, and scoped for a mainnet then base it off of `compatible`. If you’re not sure whether or not your changes are breaking, they probably are not and should build upon `compatible`. | ||
| - If the feature is scoped for hardfork and is not compatible against a running public testnet, then base it off of the hardfork branch (for example, `berkeley`). | ||
| - If it is a bug fix required for a public testnet testing upcoming hardfork then base it off of `rampup`. | ||
|
|
||
| ### Handling back-merging conflicts | ||
|
|
||
| We have CI jobs named `check-merges-cleanly-into-BRANCH` that fail if a PR introduces changes conflicting with changes in a downstream branch `BRANCH`. E.g. `check-merges-cleanly-into-develop` will check that a PR aimed at `compatible` is easily back-mergable downstream up to `develop`. PR authors must create new PRs against those branches to resolve conflicts before merging the original PR. | ||
|
|
||
| If that CI job passes, then you can proceed and no further action is needed. | ||
|
|
||
| PRs resolving merge conflicts (merge-PRs) should only be merged after the original PR is approved, and all changes from the original PR are incorporated into the merge-PRs. Consider a PR which is made from `mybranch` branch against `rampup`, and causes conflicts in `berkeley` and `develop`. In this case the workflow is as follows: | ||
| - Review and approve the original PR against `rampup` (PR-rampup). CI passes except for `check-merges-cleanly-into-*` jobs. | ||
| - Incorporate all changes from PR-rampup into a new PR against `berkeley` (PR-berkeley) and resolve conflicts. Concretely, make a new branch+PR based off of `mybranch` called `mybranch-berkeley` (for example), and then merge `berkeley` into `mybranch-berkeley`. Fix any merge errors that result. | ||
| - Keeping branches in sync: If after making e.g. `mybranch-berkeley`, you need to make changes to `mybranch`, then do so, but make sure to merge the newly updated `mybranch` into `mybranch-berkeley`. In order for the git magic to work, `mybranch-berkeley` needs to be a superset of the commits from `mybranch`, and it also needs to be merged first. | ||
| - Similarly, incorporate all changes from PR-rampup into a new PR against `develop` (PR-develop) and resolve conflicts. | ||
| - Review, approve, and merge PR-berkeley and PR-develop. They can be done in parallel. | ||
| - Rerun failing `check-merges-cleanly-into-*` jobs against the original PR-rampup and merge PR-rampup after CI is green. | ||
|
|
||
|
|
||
| The protocol team at o1labs will conduct weekly synchronization of all branches for all non-conflicting changes to ensure a smooth experience for everyone involved in the Mina repository. The protocol team will reach out to respective teams if there are any conflicting changes (due to force-merges performed mistakenly) and/or failing tests caused by code changes in the upstream branches. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.