The Importance of a Uniform Application Version Control Strategy

Perhaps no software engineering tool is quite as universally adopted throughout the industry as version control – nor is there one done in as many flavors.  Given that we define software engineering as “the multi-person development of multi-version programs”, version control is a key tool to keep things under control.

There is an often-unspoken truth when discussing version control: the technology is only one part of the practice for any given organization – there is almost always an equal amount of policy and usage convention on top of that.  Here are some of ours.

We cover the use of the GitFlow standard below and at Mercury, that is the hallmark policy and adopted convention all engineers follow.

Well-managed code bases declare on specific branch in the repository to be the “Source of Truth”.  While arguments can be made between GitFlow and Trunk-based version control (with feature/release branches clouding the picture), “master” is our Source of Truth.  Beyond the supremacy of this single Source of Truth, any discussion that an organization has about branch management policies has to acknowledge that every piece of work-in-progress in the organization is equivalent (or literally) a branch.  And thus, we get to the topic of long-lived branches.

In short, active development branches (“non-permanent” branches) should be very short-lived – they should only exist as long as is required to execute the work (user story) that led to the creation of the active development branch.  “Active development branch” has a different name depending on the organization; what we mean is the branch an engineer creates in response to pulling a new user story or ticket.  Since we purposely size our user stories to be relatively small and executable in 1-2 days, this sets an expectation on the life of individual development branches.

There are a lot of reasons for this and there has been a large body of study to back it up, but our rationale comes down to two key points:

1. the longer a branch is open, the more difficult (because of merge conflicts) merges are and
2. pull requests for a sea of code changes (lots of work committed over a long time in one commit) are BRUTAL

“Monorepo” refers to the strategy of keeping code for many projects stored in the same repository.  Given that we are a client services organization we have to clarify that we cannot (due to intellectual property restrictions) literally keep all of our organization’s code in a single repo.  “Monorepo” at Mercury refers to keeping all of a client’s code in the same repo, even if we work on multiple products for a client.  While we don’t think the monorepo is the perfect answer for all situations, we do generally prefer it to the “manyrepo“.

There are a few reasons for this bias (and honestly, a lot of it is preference) but after years of trying individual repos per client code base and a single repo per client, we find less confusion and ease of development for the monorepo variant.  Oftentimes a client’s products interact with (or even depend on) each other and cross-repo machinations are not as clean as just having the entire contained system in a single repo.  This choice also fosters greater opportunities for and likelihood of code reuse (rather than reinventing across related repos).

Vidiu Platon

Conclusion

While we have certainly left out several nuances and team-specific details in this post, it ably summarizes Mercury’s GitFlow-based version control strategy that we apply across all teams and products.  While we cannot claim to never have issues with this strategy, it has greatly improved the reliability of day-to-day commits, builds and releases and also dramatically reduced the pain of former long-lived branch merges.