Commit

Git Commit with Quality Gates

Enforce code quality before every commit.

Workflow (MANDATORY ORDER)

1. Quality Gates (BLOCKING - must pass)

   ./scripts/quality-gates.sh
   

   • Validates >90% test coverage
   • Runs all tests with strict warnings
   • Checks security vulnerabilities
   • Verifies code quality standards
   • Checks for .py or .sh files in repository root (forbidden)

   If quality gates FAIL: STOP. Fix issues before proceeding.

2. Check Status

   git status
   git diff --stat
   

3. Stage Changes

   git add -p  # Interactive staging for atomic commits
   # OR
   git add <specific-files>
   

4. Create Commit (use message format below)

   git commit
   

5. Sync with Remote

   git pull --rebase
   

6. Handle Conflicts (if any)

   • STOP - DO NOT AUTO-FIX
   • Notify user for manual resolution
   • Only proceed after user confirms resolution

7. Push

   git push
   

Commit Message Format

type(scope): Brief description (50 chars max)

- Why this change was necessary from user perspective
- What problem it solves or capability it enables
- Reference issue/ticket numbers if applicable

Commit Types

Message Rules

• Subject: 50 chars max, capitalized, no period
• Body: Wrap at 72 chars
• Use imperative mood: "Add feature" not "Added feature"
• Explain WHY from user perspective, not WHAT code changed

Examples

Good:

feat(search): Add filters to help users find documents faster

Users were spending too much time scrolling through results.
New filters reduce search time by 60% in user testing.

Fixes #123

Bad:

improved stuff

Atomic Commit Principle

• Each commit = ONE logical change
• Commit must compile and pass tests
• Use git add -p for partial staging

Repairing Existing Commits on a PR Branch

CI enforces commitlint (commitlint.config.cjs): header ≤ 100 chars AND every body/footer line ≤ 100 chars. When a PR branch already fails Commit Message Lint (LESSON-023/024):

# 1. Enumerate failures locally against the PR base
npx commitlint --from <base-sha> --to HEAD --verbose

# 2. Drop no-op noise commits non-interactively (e.g. re-trigger commits)
GIT_SEQUENCE_EDITOR='sed -i "/re-trigger workflow runs/d"' git rebase -i <base-sha>

# 3. Rewrap every long line mechanically, without changing content
#    (fold -s keeps word boundaries; verify the content diff is empty)
git filter-branch -f --msg-filter 'fold -s -w 100' -- <base-sha>..HEAD
git diff <old-head-sha> HEAD --stat   # must be empty
npx commitlint --from <base-sha> --to HEAD --verbose   # 0 problems

# 4. Push the rewritten history
#    --force-with-lease only; never --force when others may have pulled
git push --force-with-lease origin <branch>

Also:

• Run cargo fmt --all before pushing — CI Quick Check fails on fmt drift.
• Never add chore(ci): re-trigger workflow runs empty commits; instead fix the underlying failure or re-run the workflow from the Actions UI.

References

• AGENTS.md - Required Checks Before Commit

Optional Pre-Push Checks

For larger changes:

./scripts/check-doctests.sh
./scripts/check_performance_regression.sh

References

• AGENTS.md - Required Checks Before Commit