/common-git-collaboration

name: common-git-collaboration
description: Enforce version control best practices for commits, branching, pull requests, and repository security. Use when writing commits, creating branches, merging, or opening pull requests.
metadata:
  triggers:
    keywords:
    - commit
    - branch
    - merge
    - pull-request
    - git

Git & Collaboration

**Priority: P0 (CRITICAL)**

1. Write Conventional Commits

• Format: `<type>(<scope>): <description>` (e.g., `feat(auth): add login validation`).
• Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`.
• Use imperative mood: "add feature" not "added feature".
• One commit = one logical change — no mega-commits.

See [implementation examples](references/implementation.md) for conventional commit examples.

2. Manage Branches

• Name with prefixes: `feat/`, `fix/`, `hotfix/`, `refactor/`, `docs/`.
• Create new branch for every task to keep main stable and deployable.
• Never push directly to `main` or `develop` — use Pull Requests.
• Pull before you push to resolve conflicts locally.
• Prefer `git rebase` over merge for linear history on feature branches.
• Use `git rebase -i` to squash messy commits before pushing.

3. Submit Quality Pull Requests

• Limit to < 300 lines of code for effective review.
• State what changed, why, and how to test. Link issues (`Closes #123`).
• Self-review for obvious errors before requesting peers.
• PRs must pass all CI checks (lint, test, build) before merging.

4. Protect Secrets and Metadata

• Never commit `.env`, keys, or certificates — use `.gitignore` strictly.
• Use `husky` or `lefthook` for local Git Hooks enforcement.
• Tag releases with SemVer (`vX.Y.Z`) and update `CHANGELOG.md`.

Anti-Patterns

• **No direct push to main**: All changes via PR, no exceptions.
• **No mega-commits**: One commit = one logical change. Split large ones.
• **No secrets in history**: Use `git filter-repo` to purge; rotate secret.

References

• [Clean Linear History & Rebase Examples](references/CLEAN_HISTORY.md)