Commiting to Git
+---------+ +-------------------+
| 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/
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-hookwill flag this now, preventing you from pushing it to the repository.
- 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.
- Automated Testing: Every push to any branch triggers automated tests to validate changes.
- Build and Deployment Automation: Commits merged into the main branch after passing reviews trigger automatic builds and deployments through our pipeline.
- 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.
Avoid force push unless really neccessary
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.
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.
Good merges are characterized by thorough testing and inclusive reviews, which enhance the project and maintain its health.
Avoid merges that skip process checks, such as bypassing tests or reviews, which can lead to unstable releases and technical debt.
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.
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-msgfile 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-msgThis 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-pushfile in .git/hooks
#!/bin/sh
# Pre-push hook to run local unit tests
# Check if branch name follows our agreed on format
branch_name=$(git rev-parse --abbrev-ref HEAD)
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."
# Run local unit tests
echo "Running local tests..."
yarn test:all
# Check if the tests were successful
if [ $? -ne 0 ]; then
echo "Tests failed, aborting push."
exit 1
fi
echo "Tests passed - proceeding with push."
exit 0- Make the script executable:
chmod +x pre-push- 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
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.