Git Flow

This document explains the branching strategy and workflow used in the Stoplight project.

Branch Structure

Main Branches

main

• Contains the latest stable release code
• All releases are tagged in this branch using semantic versioning (e.g., v1.2.3)
• The HEAD of main should always be tagged - every commit represents a release
• This branch should always be in a deployable state
• Direct commits to main are not allowed - only merges from release branches

develop

• Integration branch for ongoing development
• Contains the latest development changes that will be included in the next release
• Feature branches are merged into develop
• Serves as the base for creating new release branches

Supporting Branches

Release Branches: release/*

• Created from develop when preparing a new release
• Naming convention: release/v1.2.3 (include the version number)
• Used for final testing, bug fixes, and release preparation
• Once ready, merged into both main and develop
• Deleted after the release is complete

Workflow

Starting a New Feature

1. Create a feature branch from develop
2. Work on your feature
3. Open a pull request to merge back into develop

Preparing a Release

1. Create a release branch from develop: git checkout -b release/v1.2.3 develop
2. Perform final testing and bug fixes on the release branch
3. Update version numbers and changelog if needed
4. When ready to release:
   • Merge the release branch into main
   • Switch to main branch and execute rake release which:
     • Tags the hotfix release (e.g., v1.2.4)
     • Publishes the ruby gem
     • Pushes tags to the repository
   • Merge the release branch back into develop (to include any release fixes)
   • Merge conflicts could happen at this stage - resolve them locally and push develop.
   • Delete the release branch

Hotfixes

When critical bugs are found in the latest release that need immediate fixes:

1. Create a hotfix branch from main: git checkout -b hotfix/v1.2.4 main
2. Make the necessary fixes on the hotfix branch
3. Test the hotfix thoroughly
4. When ready to release:
   • Merge the hotfix branch into main
   • Switch to main branch and execute rake release which:
     • Tags the hotfix release (e.g., v1.2.4)
     • Publishes the ruby gem
     • Pushes tags to the repository
   • Merge the hotfix branch back into develop to ensure the fix is included in future releases
   • Merge conflicts could happen at this stage - resolve them locally and push develop.
   • Delete the hotfix branch

Important: Always tag hotfixes to maintain the rule that main HEAD is always tagged.

Guidelines

• Keep the main branch stable at all times
• The HEAD of main must always be tagged - every last commit in main represents a release
• All development work happens in feature branches.
• Use descriptive commit messages
• Ensure CI passes before merging
• Delete feature and release branches after they're merged to keep the repository clean

Further Reading

• A successful Git branching model