Our Source Control Best Practices

We’ve noticed that few organizations outright describe how they do source control. Planning how you’ll work with source control is not always a straightforward answer, and it will be different based on the size of a software engineering team and the unique problems they face.

Seeing an example might be helpful - even if some things won't work for your team. This post outlines some of the specifics about how we manage source control as Doppler. We don’t think how our team works should be a secret. The more we share about our operational methodologies, the more we can foster an environment of learning and improvement within our team and across the broader industry.

This post highlights some of the components we think are the most helpful/important to us. Some of this may seem really basic. However, we hope comparing with what you may be doing is still beneficial.

Git Branching Strategies

• Work branch name conventions are name/something or initials/something
  • e.g. andre/fix-the-thing
  • At any given time, an engineer on our team might be working on 1-2 branches of their own, plus reviewing 2-3 branches from other authors. It’s much easier to keep things straight when branches have friendly names (instead of “feat/eng-8731”)
• Rebasing work branches is encouraged.

How We Use Commits

• We care deeply about commits and how they are structured. Well-structured commits serve as a critical review tool and can help us reason why changes were made years after the fact. These are some excellent guides on the commit style we follow:
  • Writing good commit messages - John Högberg
  • How to Write a Git Commit Message - Chris Beams
  • Commit message subjects should be no more than 60 characters long.
  • If the commit does not impact runtime behavior (e.g., it moves code around), append (noop) to the message.
• At a high level, commits should be logically atomic, well-described, and change-oriented. Commit messages should be phrased in the imperative. The message should answer the question: "If I apply this commit, what will it do? Well, it will..."
  • ✅ Add validation to the creation endpoint
  • ❌ Added validation to the creation endpoint

Our Pull Requests Practices

• An author submits a PR and adds one or more groups, depending on the areas of impact. We use GitHub Code Owners to automate this. Reviewers from those groups are notified and add themselves to the PR if they would like the PR to be blocked until they are approved.
• Once all necessary approvals have been submitted, the author may merge at will.
  • The author has the most context around their changes and should but the one who ultimately decides when a change should be merged.
• When a reviewer submits a question or suggestion, it is the responsibility of the author to address the comment and resolve it.
• A ticket (we use Linear) should be created for all PRs unless there is a documented reason for the exception.
  • It sometimes feels trivial to write a ticket just to immediately put up a PR to close it. However, this policy allows us to take advantage of related issues in Linear, so there’s a paper trail connecting features and bug fixes.

Pull Request Prefix Review Terms

We use specific language in our review comments to indicate the action we expect. We - did - not - invent - this. However, we have implemented this idea in our own way and found that it works well for us. Check out our short post for more details on how we use Code Review Comment Prefixes for Clearer Feedback.

Addressing comments that require code changes

• We like to use commits as a review tool. A reviewer should be able to walk through the commits in your PR and understand how you made the changes and how they come together. We wrote a post on how we are Improving Code Reviews with Storytelling that covers these details in full.
• We expect that a PR author rarely gets an extensive PR perfect on the first try (otherwise, what would be the point of review!). As a result, changes often need to be made during the review.
  • We also like a clean git history post-PR-merge. As a result, we recommend squashing any changes made during the review back into the commits that were there originally. In other words, the git history should be like you did get it perfect on the first try.
  • These squashes/amends/new commits should happen during the review process. Authors should feel free to force-push changes to their branches. It’s helpful to leave a comment when doing so, such as “Above force-push addresses X, Y, Z” (bonus points for linking to the force-push diff).
  • Here are a few tools that we use to make it easier to fixup changes into earlier commits:
    • review-tags
      • A script for tagging a review branch to capture different stages of the review.
    • lazygit
      • A TUI that makes it easy to rebase changes.

Reviewer Responsibilities

As a PR author, it’s useful to know what reviewers will be looking for in their reviews. We have created an internal checklist outlining those responsibilities. This checklist focuses on higher-level software quality goals and specific edge cases that have bitten us in the past and are challenging to automate guards around.

Comments We Dont Leave

We only leave comments for “improvements.” A change is an improvement if all or nearly all of the project's engineers agree that it is. The improvement should only be adopted if the cost to change/retest is worth the benefit.

As a result, we don’t leave comments for improvements where the benefit is clearly not worth the cost. We use “nit” and “supernit” to indicate that the cost/benefit is near zero — allowing the PR’s author to make the decision

We periodically meet to calibrate on which nits/supernits we want to leave. Which should we stop calling out? Which should we streamline by writing linting rules for?

Why We Shared Our Source Control Practices

While not every practice outlined may suit every team's needs, our hope is that by sharing our methods, we encourage a broader conversation about effective source control practices. This dialogue enriches our team and the broader software development community. By pulling back the curtain on our source control operations, we invite others to reflect and innovate, fostering a culture of mutual growth that benefits us all.

If you found this post helpful, have feedback, or want to share your source control practices, please email chandler.mayo@doppler.com. We would like to hear from you!