Commiting to Git

Branching Model & Workflow details

+---------+       +-------------------+
|  Main   |<------+   Hotfix Branch   |
+----^----+       +--------^----------+
     |                     |
     |                     |
     |               +-----+------+
     +-------------> |   Feature  |
                     |   Branch   |
                     +------------+

We use a structured branching model that works best for our team collaboration, while ensuring that our main branch always remains stable and release-ready.

Key Branch Types:

Main Branch: As the name says, the main branch, which is to be stable, tested version → main/
Feature Branch: For developing new features collaboratively, merged back to main after review. → feature/
Hotfix Branch: For urgent fixes, with fast-track reviews to ensure stability in production. → hotfix/

Branch Management

Example of a good branch name

The branch follows the feature/ naming convention when adding in new features.
The branch has a good descriptive name.

Example of a bad branch name:

The branch does not follow the formatting style, and pre-hook will flag this now, preventing you from pushing it to the repository.

Life Cycle of Branches

Short-Lived Feature Branches: Merged back into main after completion to reduce complexity and integration challenges
Hotfixes for Rapid Integration: Critical fixes are rapidly deployed and integrated across all development
Regular Pruning: Regularly review and delete merged or uneccessary branches to maintain a clean repository.

Branch Integration with CI/CD

Automated Testing: Every push to any branch triggers automated tests to validate changes.
Build and Deployment Automation: Successful commits lead to automatic builds through our workflows.
Git Hooks and CI/CD: We utilize Git hooks such to ensure that only code adhering to our standards triggers the CI/CD, which maintains code quality and reduces the chance of production issues.

Commit Practices

Avoid force push unless really neccessary

Descriptive Commits

We have agreed to have clear, concise commit messages that describe the what and the why of changes:

ADD: New features or additions.
FIX: Bug fixes or corrections.
DEL: Removing code or files.
UPD: Updates to existing functionalities.

Examples of Commit Messages:

Good Commit Example:

Why it’s good:

Clear Prefix: Uses a prefix "UPD" to indicate that it's an update, which is part of the standard convention.
Descriptive: Clearly describes what was done (updating a YAML file) and why (to include an update option).
Scope Limited: Focuses on a single change which makes it easier to understand the purpose and impact of the commit.

Bad Commit Example:

Why they’re bad:

Non-descriptive Messages: The commit messages are vague, do not convey the purpose of the changes.
Inconsistent Naming: They do not follow a clear or agreed-upon naming convention which makes them harder to track in the version history. (granted this did not exist back then, but it is the best example I have now, sorry Julius)
Should Have Been Squashed: We have opted to squash merge to maintain a clean history, however this was merged as singular commits, making it more difficult to maintain a clean history.

Merging Practices

Good Merge Practices

Good merges are characterized by thorough testing and inclusive reviews, which enhance the project and maintain its health.

Avoiding Poor Merges

Avoid merges that skip process checks, such as bypassing tests or reviews, which can lead to unstable releases and technical debt.

Git Hooks

       Local Repository                     Remote Repository                      CI/CD Pipeline
+--------------------------+            +-------------------------+            +---------------------+
|                          |            |                         |            |                     |
|  pre-commit              |            |   Pull Request Checks   |            |                     |
|   +-----------+          |            |   +-------------------+ |            |                     |
|   | Lint code |          |  push      |   | Automated Review  | |            |                     |
|   +-----------+          |   +------> |   | Branch Protection | |            |                     |
|                          |            |   +-------------------+ |            |                     |
|  commit-msg              |            |                         |   trigger  |                     |
|   +---------------+      |            |                         | +--------> | Automated Tests     |
|   | Verify format |      |            |                         |            | Build Jobs          |
|   +---------------+      |            |                         |            | Deployment Tasks    |
|                          |            |                         |            |                     |
|  pre-push                |            |                         |            |                     |
|   +----------------+     |            |                         |            |                     |
|   | Verify branch  |     |            |                         |            |                     |
|   | names          |     |            |                         |            |                     |
|   +----------------+     |            |                         |            |                     |
+--------------------------+            +-------------------------+            +---------------------+

Git Hooks are scripts that Git will execute before or after events such as commit, push, and branch creation.

We use them to enforce out project's rules, and automate workflows. This helps us ensure that all team member's contributions meet the project's standards before they are integrated into the main branch.

Commit-msg Hook

There is a hook in place to prevent the team from doing commit messages that are not aligned with our designated format. ADD:, FIX:, DEL:, or UPD:

This script will automatically check the format of your commit messages. If a commit message does not adhere to the format, the commit will be rejected until corrected.

Create the commit-msg file in .git/hooks

#!/bin/sh
# Check if the commit message follows our agreed on format

# Read the commit message from file
commit_message=$(cat $1)

# Check if commit message follows format
if ! echo "$commit_message" | grep -Eq '^(ADD:|FIX:|DEL:|UPD:) .+'
then
    echo "Invalid commit message: '$commit_message'"
    echo "Commit messages must start with ADD:, FIX:, DEL:, or UPD: e.g. ADD: New feature"
    exit 1
fi

echo "Commit message follows format."

Make the script executable:

chmod +x commit-msg

Pre-push Hook for Branch Names

This hook is in place to maintain a consistency between all of the branch names that we have so we do not have situations such as:

feature/
feat/
features/

This hook ensures that all branch names adhere to our naming convention: main, feature/, or hotfix/.

Create the pre-push file in .git/hooks

#!/bin/sh
# Check if branch name follows our agreed on format

# Get current branch name
branch_name=$(git rev-parse --abbrev-ref HEAD)

# Check if the branch name fits format
if ! echo "$branch_name" | grep -Eq "^(main|feature/.+|hotfix/.+)$"; then
    echo "Error: Branch name '$branch_name' does not fit our naming convention"
    echo "Allowed patterns: 'main', 'feature/*', 'hotfix/*'"
    exit 1
fi

echo "Branch name fits naming convention."
exit 0

Make the script executable:

chmod +x pre-push

Version Control Best Practices

Pull Regularly: Keep feature branches up-to-date with the main branch
Protect Main Branch: Use pull requests only for merging
Commit Size: Small, frequent, and descriptive commits

Collaborative Practices for Git

Peer Reviews:

Every change undergoes a review to ensure code quality and consitency, but also share knowledge within the team.

Regular Syncing:

Regularly update your branches from main to minimize merge conflicts and integrate your changes smoothly.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly