Git branching strategy I am planning to follow for my open-source libraries

[thetutlage]

The main, develop, production, and staging branching works excellent for applications deployed to a particular environment. Since you always have one copy of the code running somewhere in the cloud.

However, the same strategy isn't helpful when publishing open-source (or private) libraries, where each library version is meant to be long-lived on a registry. Depending on your releasing strategies, you might also want to backport bug fixes to published versions.

The first step should be to maintain one branch per major release, as this allows backporting bug fixes to an older version, even if that is meant to be done rarely. We will come back to when these branches should be created.

Getting rid of the main branch

What is the main branch anyway?

• Is it the development branch?
• Is it the branch that contains changes for the current release? But shouldn't that be the branch named after the major release? For example, Branch 8.x.x.

Is it the branch containing the changes (including breaking changes) for the future release? If so, shouldn't we just name it after that release version? For example, if the upcoming version is 9.0.0, then the branch could be 9.x.x.

Let's only have version branches

Let's continue with what I have to say, and then we can tell if it makes sense.

• From day one, we will start with a version branch, 1.x.x, which will also be the default branch.
• If v1 is unstable, all the releases will be made with beta tags and appropriate version numbers (i.e., 1.0.0-beta.0).
• Once v1 gets stable, another release will be made with the latest tag.
• All future non-breaking improvements and bug fixes will target the 1.x.x branch.
• Someday, we will have to introduce breaking changes, which will give birth to a new branch called 2.x.x.
• The newly created 2.x.x branch will be used for future development with features/changes that should not be included in v1.
• However, if, in the meantime, a bug fix has landed into v1, then we will merge that change into the 2.x.x branch as well.
• Finally, when we are ready to make the stable release, we will mark 2.x.x as the default branch and cut a new release.

The mental model here is simple. All work is done against a specific version of the library (that is how it is in reality), and the Git branches should reflect that.

The main doesn't mean anything. If you are working on a future release, make a branch for that future major version, but do not make it the default branch yet.

Branches will diverge

Since each version is allowed to evolve on its own (especially if you allow backporting bug fixes across major versions), the branches will eventually diverge, and that's okay. That's the reality of libraries—two major versions aren't the same. In fact, in some cases, they might have different project structures, underlying tooling, and so on.

Prior Art

• Symfony seems to follow the same strategy
• Laravel, Node.js, Fastify, Angular seems to follow a variation of it with main branch for active development of future versions