Play 6: Build a Process Around Version Control Best Practices

Utilize version control for team collaboration and communication

Collaboration is key to any successful software development effort. Software development teams turn to robust, consistent version control processes to transparently share the specifics of progress with both stakeholders and other developers. Teams that can coordinate all changes in a software project, utilizing fast branching and frequent merging using trunk-based development, help members quickly share feedback, leading to immediate, actionable improvements. Version control best practices help software development teams collaborate and communicate through code using trunk-based development to meet the demands of stakeholders. 

---

Team Collaboration through Trunk-Based Development

Trunk-based development is a source-control branching model, where developers collaborate on code in a single canonical branch and resist temptation to create other long-lived development branches. By employing well-practiced techniques, teams avoid merge complications, do not break the build, and promote rapid testing, QA and deployment.

---

Commit Related Changes

A commit should be a package for related changes. For example, fixing a bug and adding a feature should produce two separate commits. Small feature-specific commits make it easier for other developers to understand the changes embodied by a commit and roll them back if something goes wrong. 

---

Commit Often

Committing often tends to keep commits smaller and helps developers write more focused commit messages that contain only related changes. Frequent commits allow developers to share code more frequently with others, making it easier for everyone to integrate changes sooner. Committing often minimizes merge conflicts. 

---

Don’t Commit Half-Done Work

Only commit code when it’s complete. This doesn’t mean a developer needs to entirely complete a large feature before committing. In this case a decomposition of large features into smaller logical sub-parts that can be committed early and often is preferred. The software repository should not be treated as the backup device. Discourage commits to simply checkpoint work at the end of the day. If a developer needs a clean working copy, consider “Stashing” instead of using a separate branch for this purpose.

---

Test Before Committing

Encourage developers to resist the temptation to commit something that they just got working and think might be complete. Verify completeness with tests at the unit level. Include those unit tests in the commit. Tests help other developers understand changes and serve as documentation.

---

Write Good Commit Messages

Begin each commit message with a short summary of changes. Separate it from the body of the commit message by including a blank line. The commit message should address the following: 

• What was the rationale for the change?  
• How does this change differ from the previous implementation? 
• Does the body of the message describe what was changed and why?
• The message should not assume the viewer already understands the problem.

---

Develop a Branching Strategy and Use Branches

Make quick and easy branching a central requirement from day one. Branches are the perfect tool to help you avoid mixing up different initiatives of development. Use branches extensively in your development workflows—for new features, bug fixes, even half-baked ideas or proof-of-concept demonstrations.

---

Develop a Branch-Based Development Workflow

Choose a workflow that can best organize your project and drive your automation. Long-running branches, topic branches, merge or or rebase, and git-flow are all options. Which one you choose depends on—your project, your overall development and deployment workflows, the hooks needed to trigger aspects of your CI/CD automation pipeline, and you and your teammates’ personal preferences. Whatever you choose, be sure to agree on a common workflow that everyone follows.

---

Define Code Owners

Code Owners are responsible for ensuring stability for a code artifact through enforcement of agreed upon standards. As projects grow in both numbers of repositories and numbers of developers, it becomes difficult to know who is responsible for what parts of the codebase and who should be reviewing proposed changes. Define a Code Owners group for each software repository to make clear which performers should be selected as reviewers for proposed changes.