Trunk-Based Git Model

What Is Trunk-Based Development?

To create high-quality software, we must be able to trace any changes and, if necessary, roll them back. In trunk-based development, developers frequently merge minor updates into a shared repository, often referred to as the core or trunk (usually the main or master branch). Within trunk-based development, developers create short-lived branches with only a few commits. This approach helps ensure a smooth flow of production releases, even as the team size and codebase complexity increase.

• Main branch usage - Engineers actively collaborate on the main/master branch, integrating their changes frequently
• Short-lived feature branches - Goal is to complete work on these branches quickly and merge them back into the main/master branch
• Frequent integration - Engineers perform multiple integrations daily
• Reduced branching complexity - Maintain simple branching structures and naming conventions
• Early detection of issues - Integrations aid in identifying issues and bugs during the development phase
• Continuous Delivery/Deployment - Changes are always in a deployable state
• Feature toggles - Feature flags used to hide incomplete or work-in-progress features
  

Trunk-Based Development (Image Source )

Benefits of Trunk-Based Development

Here are some benefits of trunk-based development:

• Allows continuous code integration
• Reduces the risk of introducing bugs
• Makes it easy to fix and deploy code quickly
• Allows asynchronous code reviews
• Enables comprehensive automated testing

Proposed Approach for a Smooth Transition

Transitioning to a trunk-based Git branching model requires careful planning and consideration. Here’s a comprehensive solution addressing various aspects of the process:

Current State Analysis

• Conduct a thorough analysis of the current version control and branching strategy.
• Identify pain points, bottlenecks, and areas that hinder collaboration and integration.

Transition Plan

• Develop a phased transition plan to minimize disruptions and get it approved by the Product team.
• Clearly communicate the plan to the development and QA teams.
• Define milestones and success criteria for each phase.

Trunk-Based Development Model

• Establish a single integration branch (e.g., “main”, “master” or “trunk”).
• Allow features to be developed and tested on the feature branch first without affecting the user experience.
• Define clear guidelines for pull requests (PRs) to maintain code quality.
• Encourage peer reviews and collaboration during the code review process.
• Develop a robust GitHub Actions pipeline to automate the build, test, and deployment processes.
• Add GitHub Actions to trigger automated workflows upon code changes.

Automated Testing

• If automated tests are not currently in use, begin creating a test automation framework (choose it wisely) as it will serve as a backbone in the long run.
• Assuming there is currently no Test Case Management (TCM) tool like TestRail, test cases will be written either in Confluence or in Excel.
• Strengthen the automated testing suite to cover Smoke, Integration, Confidence, and Regression tests.
• Integrate automated tests into the GitHub workflow for rapid feedback.
• Create and schedule a nightly confidence test job that will act as a health check of the app and will run every night according to a specified schedule. The results will be posted daily on a Slack/Teams channel.

Monitoring and Rollback Procedures

• The QA team should follow the Agile process, where for each new feature, the test plan and automated tests should be prepared before deployment. Dev and QA must go hand in hand.
• Implement monitoring tools to detect issues early in the development process.
• Establish rollback procedures to quickly revert changes in case of unexpected problems.

Documentation and Training

• Ensure each member of the engineering team is well-versed in the GitHub/Release workflow, from branch creation to production release.
• Develop comprehensive documentation detailing the new branching model and associated best practices.
• Conduct training sessions for the development and QA teams to facilitate adaptation to these changes.

Communication and Collaboration Plan

• Clearly communicate the benefits of the trunk-based model to the entire organization; conduct regular sessions throughout the initial year.
• Foster a culture of collaboration among Devs, QA, Product, and Stakeholders, encouraging shared responsibility.
• To enhance collaboration between Dev and QA, consider Sprint Planning, identifying Dependencies, Regular Syncs, Collaborative Automation, Learning Sessions, and holding regular retrospectives together.

Key Challenges When Adopting Trunk-Based Development

• Testing: Trunk-based development requires a robust testing process to ensure that code changes do not break existing functionality. Inadequate automated test coverage may lead to unstable builds.
• Code review: With all developers working on the same codebase, it can be challenging to review all changes and ensure that they meet the necessary standards. Frequent integration might cause conflicts and integration issues.
• Automation: Automation is important to ensure that the testing and deployment process is efficient and error-free. In the absence of a rollback plan, teams may struggle to address issues promptly.
• Discipline: Trunk-based development requires a high level of discipline among team members to ensure proper adherence to the development process. Developers might fear breaking the build due to continuous integration.
• Collaboration: Coordinating parallel development on the main branch can be challenging.

Release Flow: Step by step

Branching and Commit

• Devs open a short-lived feature branch for any changes/improvements/features to be added to the codebase from the trunk OR master.
• Follow a generic format for naming :
  •  <wok_type>-<dev_name>-<issue-tracker-number>-<short-description>
• Follow the naming convention for feature branches, like: 
  • feature-shivam-SCT-456-user-authentication
  • release-v2.0.1
  • bugfix-shivam-SCT-789-fix-header-styling
• While working on it, to test changes live, devs can conduct direct testing on the local environment or review instances.
• When a commit is pushed to the feature branch, GitHub actions for the following: 
  • Unit tests 
  • PR title validation 
  • Static code analysis (SAST) 
  • Sonarqube checks 
  • Security checks (Trivy vulnerability scan), etc. will trigger automatically

Pull Request and Review

• Open a Pull Request; if the PR isn’t ready yet (make sure to add WIP), also add configured labels to PR to categorize it.
• Add CODEOWNERS into .github folder of the project. This will automatically assign (pre-configured) reviewers to your PR.
• Add pull_request_template.md to .github folder. This will show you a predefined PR template for every pull request.
• As soon as a PR is opened, a notification will be sent on Teams/Slack to inform reviewers about the PR.
• When a PR is raised, a smoke test will automatically trigger on the locally deployed app instance (with the latest changes as in the PR).
• After test completion, the test report will be sent to developers via email and notifications will be sent via Slack/Teams. Test reports and artifacts will be available to download on demand.
• Reviewers will review the PR and leave comments (if any), and then Approve/Request Changes on PR (if further changes are needed).

*If any failure is critical or major, the team will fix it in the test

Merge and Build Integration

• Once all GitHub Actions have passed, the developer/reviewer can merge the pull request into the trunk (master).
• Immediately after the PR is merged into the trunk (master), an automated build job will trigger to build the app with the latest changes in the Integration Environment.
• If the build job is successful, regression tests will automatically trigger in the Integration environment, and notifications will be sent on Teams/Slack.
• If tests fail, the QA team will examine the failures. If any issues genuinely break functionality, they will either roll back the commit OR add a HotFix.
• After resolving such issues, the team can proceed with promoting the changes to the staging environment.

Create Release Branch and Tag

• At this point, cut the release branch from the trunk, such as release-v2.0.1.
• Add rule: If the branch name starts with release, trigger a GitHub Action to build the app instance to staging.
• If the build job is a success, regression tests will automatically trigger in the staging environment, and notifications will be sent on Teams/Slack.

At this point, create a tag on the release branch e.g. ‘git tag -a -m “Releasing version 2.0.1” release-v2.0.1’

• Add rule: If a protected tag is added matching a specific pattern, then deploy the app to production.
• Send the release notes to the Teams/Slack channel, notifying them about the successful production deployment.
• QA will perform sanity testing (manual+automation) after the prod deployment.
• Upon promotion to production, any issues take precedence over ongoing work for developers, QA, and the design team in general.

* At any point, if the product or design teams want to conduct quick QA while changes are in testing, they can and should do so. This applies only to product/UI features/changes. They can also do the same during test reviews. The shorter the feedback loop, the better.

Exceptions

• If any steps are not followed in either of the promotion cases (i.e., test → staging or staging → production), it must be clearly communicated why it was skipped and should only occur under necessary conditions.
• After promotion to staging, if the team discovers any blocker/critical UI issues, the dev team will address them following the same process as described earlier.
• The only exception is for non-critical issues/UI bugs, where the product team will decide whether to proceed with promotion to production or not.
• Exceptions can occur for smaller fixes such as copy changes, CSS fixes, or config updates.
• When it’s more important to roll out fast, test/QA in later iterations. Since iterations in this platform are fast and convenient, our workflow should evolve with this in mind, and to keep it that way, always!

Conclusion

In conclusion, the Trunk-Based Git Model serves as a valuable tool in the software development landscape, particularly for teams seeking a more straightforward, collaborative, and continuous integration-focused approach. As with any methodology, its effectiveness largely depends on the specific needs, goals, and dynamics of the development team and project at hand.

If you enjoyed this story, please like and share it to help others find it! Feel free to leave a comment below. Thanks for your interest. Connect with me on LinkedIn.