Skip to content

Version control

Version control provides granular, precise, distributed mechanisms for making and socializing changes to sets of files.

Version control is a key enabler of developer productivity for projects of any size, and is the backbone of Agile, DevOps, Continuous Delivery, Infrastructure as Code, and many other software methodologies.

Version control is a core prerequisite for saferatday0 adoption and for successful software projects more generally.

Version control systems

Git is far and away the most popular version control system. It is used by 93% of developers according to the 2022 Developer Survey by StackOverflow. For this reason, saferatday0 primarily invests in Git.

Version control platforms

saferatday0 is heavily invested in GitLab, the second most popular Git hosting platform behind GitHub. This is largely due to the professional experiences of the contributors. GitLab can be self-hosted and sees use in many large enterprises as a result.

Direct support for other Git hosting platforms is planned. However, the ideas behind saferatday0 are not limited to GitLab and are compatible with any platform.

Branching

Projects should follow Trunk Based Development as it is a key enabler of productivity in the saferatday0 framework.

Developers commit directly to main, and rely on pipelines to perform automated integration testing.

This results in projects with mostly linear commit graphs and lots of tags:

  • Branches: main

  • Tags: 0.6.0, 0.5.0, 0.4.0, ...

The default branch should be named main, and should be the only long-lived branch or place where anyone expects to find code. The main branch should have branch protection enabled.

Release speed should be defended at all cost. Pipelines should be fast, stable, repeatable, and cheap. This will be made easy because projects will be small, simple, and transparent.

If bad changes slip through, this is evidence that the pipeline need to improve. The linear commit history and extensive automation make rolling back bad changes very easy, and the many small projects means the blast radius of a bad change tends to be limited.

Developers should be incentivized to make smaller changes more often, running as many pipelines as necessary.

If you are afraid to commit to main, improve your pipeline until you are not.

Merging

In saferatday0, there are many projects with different owners, and core maintainers of a project can and do marshal their changes all the way from idea to production.

Projects also rely heavily on automation for integration testing, to scale and speed up capacity for a given team.

Because of this, merge requests are often unnecessary, and merge approval not required among core maintainers.

This allows project maintainers to operate autonomously and for teams to run with a smaller number of individuals.

This model views maintainers as trusted individuals. If you do not trust your maintainers, don't give them maintainer access. (But also, why are they on your team?)

Instead, merge requests are primarily used to accept code changes from contributors outside the project team. This is a convenient mechanism for building self-service functionality in some cases.

Branches should not be around long enough for their names to matter.

Tagging

All projects are tagged as often as necessary. Releases are how projects advertise that a version is ready for consumption. The main branch may be stable but is not required to be at all times. Downstream consumers should only integrate against built artifacts created via pipeline automation.

Tags result in releases only when pipelines are successful.

  • Software libraries and applications - released on tag

  • Static sites and infrastructure projects - published on commit to default branch

All tags are created off the main branch, and tag protection should be enabled.

Tip

Failed pipelines are okay! It just means something needs to be fixed. Use the CI/CD system as often as necessary. Abundant use of CI/CD is normal and expected.

Summary

  • Tag everything except singularly static site and infrastructure projects

  • Tags create version numbers.

  • Successful tag pipelines create releases.

Versioning

Version numbering

saferatday0 projects use semantic versioning. This is primarily because it is easy to remember and understand, and because it has a website.

Version injection

saferatday0 projects rely on the version control system to determine the current version. Hard-coded version numbers are not committed to repositories. Instead, the placeholder 0.0.0 is used where a version number would be, and pipelines are adapted to inject a version number using the relevant mechanism at build time.

As a result, the correct way to create a versioned release in saferatday0 is to create a tag:

git tag 0.1.0

The only version number that matters is the one stored in Git.

Version pinning

Version pinning is used to the fullest extent allowable or made practicable by the tool or framework in question. saferatday0 projects produce two distinct pinned versions

  • Tagged commits are pinned to the tag version (with no v):

    1.2.3

  • Branch commits are pinned to the branch name and short SHA:

    main-d592ba03

Releasing

Releases are secondary resources generated at the end of build pipelines for tagged commits. In GitLab, they come in the form of GitLab Releases.

A tag will have a corresponding release only when the pipeline has completed successfully. Releases should not be created manually.

A release indicates that a tag is ready for downstream consumption.