In the last All Devs call (#10, see notes: https://docs.google.com/document/d/1--tK5GsezU9qz16hVhrBWSQNEFXmktsel4NM_RQqKXQ/edit#), we discussed a new convention for git branches across Aragon’s git repos.
The proposal is to have two active development branches:
master branch that is always publishable or deployable
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: https://github.com/nodejs/Release#nodejs-release-working-group , 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.
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.
- Difficult to release (e.g.
aragonOS, other contract-only repos)
- A mix of both (e.g.
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
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
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.