Git Methodology
Project: Open Source Languages · Team Size: 6 · Repository: GitHub/Gitea · Versioning: Semantic Versioning (SemVer)
1. Purpose
This document defines the Git workflow that every team member must follow throughout the project.
- Maintain a stable and functional codebase
- Minimise merge conflicts
- Ensure code is reviewed before integration
- Keep Git history clean and easy to understand
- Make changes traceable and accountable
- Standardise the team's development workflow
All members are expected to follow this methodology consistently from kickoff until final submission.
2. Repository Structure
The repository contains two long-lived branches.
| Branch | Purpose |
|---|---|
| main | Contains only stable, tested releases. Tagged with version numbers. Never used for day-to-day development. |
| develop | Primary development branch where completed features are integrated. Deployed to staging. |
- Never commit directly to main.
- Never commit directly to develop.
- All work must be completed on feature branches.
- All merges into develop must be done through Pull Requests.
- Only the lead merges develop → main at release time.
3. Branching Strategy
Every task should have its own branch, created from the latest version of develop.
Branch from develop, never from main. Merge back to develop via Pull Request. Only the lead promotes develop → main at release time.
4. Branch Naming Convention
| Prefix | When to Use | Example |
|---|---|---|
feature/ | Developing a new feature | feature/login-page |
bugfix/ | Fixing a bug | bugfix/login-validation |
refactor/ | Improving code without changing behaviour | refactor/auth-service |
docs/ | Documentation only | docs/setup-guide |
test/ | Writing or updating tests | test/login-api |
hotfix/ | Urgent fix to main (rare) | hotfix/security-patch |
chore/ | Configuration, tooling, or maintenance | chore/update-eslint |
Rules: lowercase only · hyphens between words · short but descriptive · no spaces · one branch = one task/story.
- ✅ Good examples
- ❌ Bad examples
feature/user-profile
feature/course-crud
bugfix/navbar-overflow
test/assessment-marking
docs/api-reference
refactor/database-layer
login
mybranch
Stuff
Fix
feature/new thing
FEATURE-EVERYTHING
5. Creating a Branch
# Always start from the latest develop
git checkout develop
git pull origin develop
# Create your branch
git checkout -b feature/your-feature-name
Never create branches from main or old commits. Always pull the latest develop first.
6. Commit Guidelines
Each commit should represent one logical change — e.g. complete login form, add API endpoint, fix validation bug, update documentation. Avoid combining unrelated work into a single commit.
A commit should be small enough to understand in 30 seconds by reading the title and message, but large enough that the project still builds and tests pass.
7. Commit Message Convention
Use Conventional Commits — a simple format that makes history readable and lets tooling (changelog generation, version bumping) work automatically.
| Prefix | When to Use | Example |
|---|---|---|
feat: | New feature | feat: implement login page |
fix: | Bug fix | fix: prevent duplicate bookings |
refactor: | Internal improvements (no behavior change) | refactor: simplify auth logic |
docs: | Documentation changes | docs: update api reference |
test: | Add or update tests | test: add login integration tests |
chore: | Maintenance, config, tooling | chore: update eslint config |
perf: | Performance improvements | perf: optimize course search query |
Rules:
- Present tense ("add" not "added")
- Lowercase after the colon
- Under 72 characters
- Describe what, not how long it took
- ✅ Good examples
- ❌ Bad examples
feat: add clinic search page
fix: prevent duplicate bookings
docs: update api documentation
refactor: split booking service
test: add login integration tests
chore: update prettier config
Updated code
Working
Changes
asdf
Final commit
WIP
8. When to Commit
Commit whenever a logical piece of work is complete:
- Feature implemented
- Bug fixed
- Tests written
- Component finished
- API endpoint completed
- Documentation updated
A teammate should always be able to pull your commit and successfully build the project.
- Broken code
- Unfinished features
- Temporary debugging code (console.logs, commented-out code)
- Large unrelated changes
.envfiles or secrets
9. Pushing Changes
git push origin feature/your-feature-name
Push regularly — don't wait several days before sharing your work. Pushing frequently reduces merge conflict risk.
10. Keeping Your Branch Updated
Before starting work each day or before opening a PR:
git checkout develop
git pull origin develop
git checkout feature/your-feature-name
git merge develop
Resolve any merge conflicts before continuing development. If conflicts are complex, ask a teammate for help — don't struggle alone.
11. Pull Request Workflow
Every completed feature must be merged using a Pull Request. No direct merges are permitted.
Opening a PR
- Push your branch:
git push origin feature/your-feature-name - Go to GitHub/Gitea → Pull Requests → New Pull Request
- Set:
- Base branch:
develop - Compare branch:
feature/your-feature-name
- Base branch:
- Verify only intended changes appear
- Give the PR a descriptive title (should match your commit message)
- Write a short description using the template below
- Assign at least one reviewer
- Submit
PR Description Template
## Summary
Brief explanation of what this PR does.
## Changes
- Added login page
- Added auth middleware
- Added validation schemas
## Testing
- Tested locally with Vitest
- No known issues
- [Optional] Link to test results
## Related Issues
Closes #123
12. Pull Request Requirements
Before requesting a review, ensure:
- Project builds successfully (
npm run build) - All tests pass locally (
npm run test) - Linter passes (
npm run lint) - No merge conflicts exist
- Code is formatted (
npm run format) - No commented-out code remains
- No debugging statements remain
- Documentation updated (if needed)
-
.envfiles not committed
Husky will catch many of these automatically on commit, but check manually too.
13. Code Review
Every Pull Request requires at least one approval before merging.
Reviewers check:
- Code correctness and logic
- Readability and naming
- Adherence to coding standards
- Test coverage and quality
- No duplicate code
- No obvious performance issues
- Compliance with API conventions
As an author:
- Respond to comments respectfully
- Explain your reasoning if you disagree
- Push fixes and re-request review
- Don't merge until approved
14. Merging Strategy
The team uses Squash and Merge — combining all commits into a single clean commit when merging into develop.
- Before squash
- After squash
c3a9f2: Added button
e1b4d8: Oops typo
f2c6a1: Fixed CSS
a7d9e2: Another fix
b8e3c4: Final fix
9k2m4p: feat: implement login page
Why squash merge?
- Cleaner Git history — easier to read and understand
- Easier to bisect bugs (
git bisectfinds the commit that broke something) - Cleaner release notes — one logical change = one line in the changelog
- Easier to revert — reverting one commit vs. reverting five
Most platforms default to allowing all merge types. Set branch protection rules to require squash merge and prevent direct pushes.
15. Deleting Branches
Once merged, delete the branch immediately:
# Delete locally
git branch -d feature/your-feature-name
# Delete on GitHub/Gitea
git push origin --delete feature/your-feature-name
Stale branches clutter the repository and confuse new team members.
16. Versioning — Semantic Versioning (SemVer)
Format: MAJOR.MINOR.PATCH
| Version | Meaning | Example |
|---|---|---|
| MAJOR | Breaking changes to the API or data model | 1.0.0 → 2.0.0 |
| MINOR | New features, backwards-compatible | 1.0.0 → 1.1.0 |
| PATCH | Bug fixes, backwards-compatible | 1.0.1 → 1.0.2 |
Examples
0.1.0— First working Basic tier (MVP)0.2.0— Intermediate tier complete (new features)0.2.1— Bug fix for a moderation issue (patch)1.0.0— Final submission with all Advanced features (major release)
- Clear contract with users/graders about what changed
- Easier to document breaking changes
- Standard across open-source software
- More precise than calendar versioning for a 6-week project
17. Git Tags
Each official release receives a Git tag, created only for stable milestone releases (roughly at sprint ends).
# Create and push a tag
git tag -a v0.1.0 -m "Basic tier complete"
git push origin v0.1.0
Tags should match your version numbers. The lead creates tags at release time.
18. Daily Workflow
- Start your day: Pull the latest
develop - Pick a task: Choose a story from the sprint board
- Create a branch:
git checkout -b feature/story-id-description - Implement: Write code, tests, docs
- Commit regularly: Small, logical commits
- Push:
git push origin feature/your-branch - Open a PR: Describe the changes, request review
- Address feedback: Respond to review comments, push fixes
- Merge: Once approved and CI passes, merge via squash
- Delete branch: Clean up after yourself
19. Team Responsibilities
- Every Team Member
- Project Lead
- Follow this Git methodology strictly
- Work only on assigned tasks
- Keep commits small and meaningful
- Push changes at least daily
- Review teammates' PRs when requested
- Resolve merge conflicts promptly
- Delete branches after merging
- Write descriptive commit messages
- Protect the
mainanddevelopbranches - Enforce this Git methodology
- Approve releases (only lead can merge develop → main)
- Create release tags
- Coordinate development milestones
- Resolve escalated conflicts
- Update version numbers and CHANGELOG
20. Summary of Rules
| Rule | Policy |
|---|---|
Direct commits to main | ❌ Never |
Direct commits to develop | ❌ Never |
| Feature branches required | ✅ Yes |
| Pull Requests required | ✅ Yes, even for small fixes |
| Code review required | ✅ Minimum one approval |
| Squash merge | ✅ Always |
| Delete merged branches | ✅ Immediately |
| Semantic versioning | ✅ Yes |
| Tag official releases | ✅ Yes |
Keep main stable | ✅ Always |
21. Appendix — Example Workflow
# Start the day
git checkout develop
git pull origin develop
# Create a feature branch
git checkout -b feature/write-1-create-course
# Implement, commit
git add src/course.model.ts src/course.controller.ts
git commit -m "feat: implement course creation endpoint"
git add tests/course.test.ts
git commit -m "test: add course creation tests"
# Push
git push origin feature/write-1-create-course
# [Open PR on GitHub]
# [Wait for CI to pass and review]
# [Address feedback if needed]
# [Merge via GitHub UI — select "Squash and merge"]
# Clean up
git checkout develop
git pull origin develop
git branch -d feature/write-1-create-course
git push origin --delete feature/write-1-create-course
Following this methodology ensures the repository stays organised, development is predictable, and collaboration across 6 people stays efficient.