Git branch convention for Aragon repos

In the last All Devs call (#10, see notes:, we discussed a new convention for git branches across Aragon’s git repos.

The proposal is to have two active development branches:

  1. A master branch that is always publishable or deployable
  2. A next (or dev?) branch that holds longer-term or breaking changes that may be broken

This structure works well for repos with contracts, which, more so than any other kind of software, typically requires a lot of preparation before any new deployment but also works well for other repos where we may need to make hotfixes or quick releases.


Is a branch that is always publishable and deployable necessary? Can’t this branch be created on demand from the latest tag?

If we take aragonOS as an example, we would have version 4 on master and version 5 on next, right? If we only expect to add bugfixes to version 4, we don’t need an active development branch for it, we can create it from the latest 4.x.x tag (assuming this will only happen rarely, it should be enough). This can be applied to all previous versions.

Does this aim to resolve a specific need when a breaking change is introduced and development is split into two active branches? If so, may I propose the opposite naming convention:

  • master , which has the breaking changes, next version (5), not deployable just yet
  • previous, or better yet, version4, which is deployable and expected to have a few more features added on

This would allow more than 2 versions being worked on at the same time (undesirable, but depends on the long term support we want to offer), similar to nodejs: , and keep backwards compatibility with the current branching model.

Edit: I think it would be the most intuitive for developers to have master as the default.

1 Like

Hmm, good points.

I’m rethinking the prior branching strategy, as a prescriptive “one-size-fits-all” won’t work well.

I see three different types of repos we maintain:

  • Immediately releasable (e.g. aragon-cli, aragon.js, aragon/aragon)
  • Difficult to release (e.g. aragonOS, other contract-only repos)
  • A mix of both (e.g. aragon-apps)

Immediately releasable repos should just follow simple git practices. One master branch, and any hotfixes can be made against both master and the target version. An example of this would be on aragon-cli: if we had large features added to master that we weren’t confident in, but still needed a hotfix (like pinning a dependency’s versions), we would make a PR to pin it, and then cherry-pick that commit to another tagged commit to release a hotfix version (with a git tag). In more difficult cases, two PRs may be necessary to patch both the master repo as well as the old tag.

Difficult to release repos should follow a master and next (or dev) strategy, where master contains the latest stable version, and next contains the current HEAD of work. The default branch should be next. This is particularly useful to signify that master is of strong quality (e.g. only audited code), but we could also switch around the branches (e.g. an audited branch that gets fast-forwarded every time master is audited).

Repos with a mix of both should follow a master and next strategy, but with the default branch being master. All difficult to deploy changes should be against next, and should not impact other code, to keep merge conflicts simple. All deployable changes should be against master, such that master is always deployable. When next is ready, it should be merged against master alongside any required updates (e.g. frontend) for those breaking changes.

I agree that keeping the default branch as master is intuitive for most developers.

At this particular point in time, I’m of the strong opinion that we should only support the latest versions of packages, and mark when a package is not compatible with a previous version (e.g. aragon.js to aragonOS). We can revisit this when the ecosystem grows larger, and we have breaking releases which are more onerous for developers to upgrade.

I took a shot at a concise summary here: Documenting the Git Branch Convention on Smart Contract Repos

1 Like