Git Conventions

PURPOSE

Defines branching strategy, commit messages, and PR processes using GitHub Issues integration.

RULES

MUST move the GitHub Issue to In Progress on the project board before starting any work.
MUST create branches prefixed with feature/ (or fix/, chore/, docs/ as appropriate) followed by the issue number and a short description: feature/<issue-number>-short-description.
MUST include the issue number (#<issue-number>) in every commit message so GitHub auto-links it to the issue.
MUST open Pull Requests targeting the dev branch — never push directly to main. There are no exceptions — migration files also go through dev like any other change (see Migration Convention).
MUST add Closes #<issue-number> in the PR description so GitHub closes the issue automatically on merge.
MUST run pnpm build before creating a PR.
MUST include unit tests or endpoint tests for PRs to the dev branch.
MUST create or update docs/features/<issue-id>-<slug>.md for every feature PR.
MUST ensure QA documentation matches /docs/features/qa-requirements for scenario coverage and security-sensitive cases.
MUST include the feature doc checklist in the PR before requesting review.
MUST self-review code before assigning a reviewer.
MUST have at least one team member approve the PR before merging.

STRUCTURE / DETAILS

Branching Strategy

main: Production-ready code
staging: Pre-production testing environment
dev: Active development — all PRs target this branch

Branch Naming

Prefix the branch with its type, then the issue number and a short description:

<type>/<issue-number>-short-description

Types:
  feature/  — new feature
  fix/      — bug fix
  chore/    — tooling, build, or maintenance
  docs/     — documentation-only changes

Examples:
  feature/42-add-login-page
  fix/17-prisma-schema-mismatch
  chore/89-bump-node-version

GitHub Issue Tracking

Every task starts and ends with a GitHub Issue. The project board is at: https://github.com/orgs/StudyBoostIO/projects/2/views/1

Find your issue in the Issues tab or on the project board.
Move it to In Progress on the project board.
Work on your branch, committing with the issue number.
Open a PR → it gets reviewed → merged into dev.
Issue moves to Done (automatically if Closes # was used, otherwise manually).

Commit Messages

Every commit must include the issue number so GitHub links it to the issue timeline:

#<issue-number> short description of what was done

Examples:
  #42 add login form component
  #42 fix validation on login page
  #17 update Prisma schema for courses

You may also use the conventional commit format with the issue number:

<type>(<scope>): <subject> #<issue-number>

Example:
  feat(auth): add google login provider #42

Types:

feat: New feature
fix: Bug fix
docs: Documentation
style: Formatting
refactor: Code restructuring
perf: Performance improvements
test: Adding tests
chore: Tooling and build changes

Pull Requests

Target branch: dev
Title format: #<issue-number> Short description (e.g. #42 Add login page)
Add Closes #<issue-number> in the PR description to auto-close the issue on merge
Add the feature documentation checklist to the PR description:

- [ ] Feature doc created/updated
- [ ] QA scenarios added
- [ ] Edge cases documented

Ensure the linked feature doc includes frontend behavior, backend behavior, and a QA scenario table with issue-based scenario IDs
At least one approval required before merging

QUICK REFERENCE

Step	Action
Start task	Move issue → In Progress on project board
Create branch	`git checkout -b <type>/<issue-number>-short-description` (e.g. `feature/42-add-login-page`)
Commit	Include `#<issue-number>` in every commit message
Push & PR	Open PR from your branch → `dev` (no exceptions — migration files also flow through `dev`)
Close issue	Add `Closes #<issue-number>` in PR description
Merge	Requires at least one approval; merge into `dev` only

EDGE CASES

Hotfixes to main MUST be backported to dev.
Migration files (backend/prisma/migrations/YYYYMMDDHHmm_*/migration.sql) follow the same PR-to-dev flow as every other change. Never push migration files (or anything else) directly to main.
If an issue is only partially resolved by a PR, do not use Closes # — move the issue back to the appropriate board column manually.

EXAMPLES

git checkout -b feature/42-add-login-page
git commit -m "#42 add login form component"
git commit -m "#42 fix validation on login page"
git push origin feature/42-add-login-page
# Open PR: title "#42 Add login page", description "Closes #42", target: dev