Git Conventions

Conventional Commits

Format: <type>(<scope>): <description>

feat(auth): add OAuth2 login with Google
fix(api): handle null response from user endpoint
docs(readme): add deployment instructions
refactor(hooks): extract shared fetch logic into useApi
test(auth): add integration tests for login flow
chore(deps): update react to v19.1

Types

Rules

• Type is required and lowercase.
• Scope is optional, lowercase, describes the area of change (auth, api, ui, deps).
• Description is required, imperative mood ("add", not "added" or "adds"), lowercase, no period at the end.
• Body (optional) explains why, not what. Wrap at 72 characters.
• Breaking changes: add ! after the type/scope or include BREAKING CHANGE: in the footer.

feat(api)!: change authentication to use JWT tokens

BREAKING CHANGE: The session-based auth endpoints have been removed.
Clients must now use Bearer tokens in the Authorization header.

Multi-Line Commits

fix(payments): prevent duplicate charge on retry

The retry logic was not checking if the original charge succeeded
before attempting a new one. Added idempotency key validation
to the charge endpoint.

Closes #1234

Branching Strategy

Branch Naming

feature/add-user-dashboard
fix/null-pointer-in-checkout
chore/upgrade-dependencies
docs/api-authentication-guide
refactor/extract-payment-service

Pattern: <type>/<short-description> using kebab-case.

Trunk-Based Development (Recommended)

main ─────●────●────●────●────●─────
           \       /      \       /
            ●────●          ●────●
          feature/x       fix/y

• main is always deployable.
• Short-lived feature branches (1-3 days).
• Merge via squash or rebase to keep history linear.
• Use feature flags for long-running work instead of long-lived branches.

Git Flow (When Required)

main    ─────●──────────────●───────
              \            /
develop ───●───●───●───●───●────●───
            \     /     \     /
             ●───●       ●───●
           feature/x   feature/y

• main — production releases.
• develop — integration branch.
• feature/* — branch from develop, merge back to develop.
• release/* — stabilization before production.
• hotfix/* — urgent fixes from main.

Use trunk-based development unless the project specifically requires Git Flow.

Commit Best Practices

• Atomic commits: Each commit is one logical change that compiles and passes tests.
• Commit often: Small, frequent commits are easier to review, bisect, and revert.
• Don't commit generated files: Add build outputs, lock files changes (when unintended), and artifacts to .gitignore.
• Don't commit secrets: Never commit .env, API keys, credentials, or tokens.
• Sign commits: Use git commit -S for verified authorship.

Pull Request Conventions

PR Title

Follow the same conventional commit format:

feat(dashboard): add real-time notifications widget
fix(auth): resolve token refresh race condition

PR Description Template

## Summary

Brief description of what this PR does and why.

## Changes

- Added notification WebSocket connection
- Created NotificationBell component
- Updated header layout to include notifications

## Testing

- [ ] Unit tests pass
- [ ] Manual testing in staging
- [ ] Tested on mobile viewport

## Screenshots

(if applicable)

PR Best Practices

• Keep PRs small (< 400 lines of diff when possible).
• One concern per PR — don't mix refactoring with feature work.
• Self-review before requesting reviews.
• Respond to all review comments, even if just "Done" or "Won't fix because...".
• Squash merge to keep main history clean.

Merge Strategies

Default recommendation: Squash merge for feature branches into main. This gives a clean, bisectable history where each commit represents one complete feature or fix.

.gitignore Essentials

# Dependencies
node_modules/

# Build output
dist/
build/
.next/
out/

# Environment
.env
.env.local
.env.*.local

# IDE
.vscode/settings.json
.idea/

# OS
.DS_Store
Thumbs.db

# Debug
*.log
npm-debug.log*

# Test coverage
coverage/

Useful Aliases

git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm "commit -m"
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate -20"
git config --global alias.amend "commit --amend --no-edit"
git config --global alias.unstage "reset HEAD --"