Git Branching Strategy

This document outlines our Git branching strategy, which is based on a modified version of the GitFlow workflow. This strategy helps us manage our development process more effectively and maintain a clean, organized repository.

Git Branching Strategy

How It Works

Our workflow uses two main branches to record the history of the project:

Branch	Purpose
`main`	Stores the official release history
`develop`	Serves as an integration branch for features

Note: All commits in the main branch are tagged with a version number.

Tip: To view all branches, use git branch -a. To switch between branches, use git checkout <branch-name>.

Version Numbering

We use Semantic Versioning (SemVer) for our version numbers. The format is MAJOR.MINOR.PATCH:

MAJOR version for incompatible API changes
MINOR version for backwards-compatible functionality additions
PATCH version for backwards-compatible bug fixes

Example: 1.2.3

Tip: When creating a new version tag, use an annotated tag: git tag -a v1.2.3 -m "Release version 1.2.3"

Branch Types

Feature Branches

Purpose: Develop new features for the upcoming or a distant future release
Branch off from: develop
Merge back into: develop
Naming convention: feature/feature-name

Each new feature should reside in its own branch, which can be pushed to the central repository for backup/collaboration. Feature branches use develop as their parent branch and should never interact directly with main.

Troubleshooting: If you accidentally started working on develop, you can create a new feature branch and move your changes:
git checkout -b feature/your-feature-name
git commit -am "Your changes message"
git checkout develop
git reset --hard origin/develop

Release Branches

Purpose: Prepare for a new production release
Branch off from: develop
Merge back into: develop and main
Naming convention: release/x.y.z

Release branches are created when it's time to prepare for a new software release.

Once created, no new features can be added
Only bug fixes, documentation, and other release-oriented tasks are allowed
When ready, the release branch is merged into main (tagged with a version number) and back into develop

Tip: Use git flow release start x.y.z to start a new release branch if you're using git-flow extensions.

Hotfix Branches

Purpose: Quickly address critical issues in production
Branch off from: main
Merge back into: main and develop
Naming convention: hotfix/issue-description

Hotfix branches allow for rapid response to critical production issues without interrupting the main development workflow. They apply focused changes to the main codebase and are immediately merged into both main and develop to ensure consistency.

Important: After merging a hotfix, increment the PATCH version number and create a new tag.

Workflow Example

Follow these steps to implement our Git branching strategy:

Create a feature branch:

git checkout -b feature/new-feature develop

Work on the feature and commit changes:

git add .
git commit -m "Implement new feature"

Push the feature branch to the remote repository:
```
git push -u origin feature/new-feature
```
Create a pull request to merge the feature into develop:
- Go to Github
- Create a new pull request from feature/new-feature to develop
- Assign reviewers and wait for approval
- Once approved, merge the pull request
Create a release branch when ready:
```
git checkout -b release/1.0.0 develop
```
Make release-specific changes and push the release branch:
```
git push -u origin release/1.0.0
```
Create pull requests to merge the release into main and develop:
- Create a pull request from release/1.0.0 to main
- Create another pull request from release/1.0.0 to develop
- Assign reviewers and wait for approval
- Once approved, merge both pull requests

After the release is merged, tag the release on main:

git checkout main
git pull origin main
git tag -a v1.0.0 -m "Release version 1.0.0"
git push --tags

For hotfixes, create a hotfix branch from main:
```
git checkout -b hotfix/critical-bug main
```
Fix the issue and push the hotfix branch:
```
git push -u origin hotfix/critical-bug
```
Create pull requests to merge the hotfix into main and develop:
- Create a pull request from hotfix/critical-bug to main
- Create another pull request from hotfix/critical-bug to develop
- Assign reviewers and wait for approval
- Once approved, merge both pull requests

After the hotfix is merged, tag the new version on main:

git checkout main
git pull origin main
git tag -a v1.0.1 -m "Hotfix version 1.0.1"
git push --tags

Tip: Always use pull requests for merging into main and develop. This ensures proper code review and maintains a clean history.

Tip: Always push your tags to the remote repository: git push --tags

Troubleshooting

Merge conflicts: If you encounter merge conflicts, resolve them manually in the conflicting files, then:
```
git add <conflicting-files>
git commit -m "Resolve merge conflicts"
```
Accidentally committed to wrong branch: Use git reset to undo the commit, then stash your changes:
```
git reset HEAD~1
git stash
git checkout correct-branch
git stash pop
```
Need to undo a merge: If you've merged but haven't pushed, you can use:
```
git reset --hard HEAD~1
```
Be cautious with this command as it discards changes.
Cherry-picking commits: To apply a specific commit from one branch to another:
```
git cherry-pick <commit-hash>
```
Forgot to create a feature branch: If you've made changes directly on develop:
```
git stash
git checkout -b feature/your-feature
git stash pop
```

Git Branching Strategy

Table of Contents​

How It Works​

Version Numbering​

Branch Types​

Feature Branches​

Release Branches​

Hotfix Branches​

Workflow Example​

Troubleshooting​

Table of Contents