mantimon-tcg/CONTRIBUTING.md

Contributing to Mantimon TCG

Git Commit Guidelines

Pre-Commit Hooks

CRITICAL RULE: Never use --no-verify without explicit approval.

This project has pre-commit hooks that run:

• ESLint (catches undefined variables, unused imports, syntax errors)
• TypeScript type checking (catches missing imports, type errors)
• Tests (ensures nothing breaks)

These hooks are required to catch bugs before they enter the codebase.

When Hooks Fail

If the pre-commit hook fails:

✅ DO:

1. Read the error message carefully
2. Fix the errors in your code
3. Commit normally (hooks will pass)

❌ DO NOT:

1. Use --no-verify to bypass the hooks
2. Ignore lint/type errors
3. Assume "it will be fine"

Exception Process

If you believe you must bypass hooks (extremely rare):

1. Ask for approval first: "I need to use --no-verify because [reason]"
2. Wait for explicit approval
3. Document why in the commit message
4. Fix the issues in a follow-up commit immediately

Why This Matters

Real Example: In PR #X, commits were made with --no-verify to bypass pre-existing lint errors. This caused:

• Missing imports that weren't caught until code audit
• Runtime errors that would have been caught by TypeScript
• Hours of debugging that could have been prevented

The pre-commit hook would have caught these issues in 5 seconds.

Common Scenarios

"But there are pre-existing lint errors!"

Solution: Fix them first in a separate commit:

# Fix pre-existing errors
npm run lint -- --fix
git add .
git commit -m "Fix pre-existing lint errors"

# Now do your work with hooks enabled
git add my-feature.ts
git commit -m "Add new feature"  # Hooks will pass

"The hook is taking too long!"

The hooks are optimized to only check changed files. If they're slow:

• Check if you have too many staged files
• Consider committing in smaller chunks
• Don't bypass - the time saved now will cost hours later

"I'm just fixing a typo!"

Even typo fixes should pass hooks. If hooks fail on a typo fix, something is wrong with the surrounding code that needs addressing.

---

Code Quality Standards

TypeScript

• All code must pass npm run typecheck
• No any types without justification
• Explicit return types on functions
• Proper imports (no missing or unused)

ESLint

• All code must pass npm run lint
• No unused variables or imports
• Follow project style guide
• Use eslint-disable sparingly with comments explaining why

Testing

• All code must pass npm run test
• New features require tests
• Bug fixes require regression tests

---

Pre-Commit Hook Details

Located at: .git/hooks/pre-commit

Backend checks:

• Black formatting (black --check app tests)
• Ruff linting (ruff check app tests)
• Pytest (pytest --tb=short -q)

Frontend checks:

• ESLint (npm run lint)
• TypeScript (npm run typecheck)
• Vitest (npm run test)

All checks must pass before commit is allowed.

---

Emergency Bypass Procedure

Only with explicit approval:

# 1. Get approval first
# 2. Document in commit message:
git commit --no-verify -m "Emergency fix: [issue]

This commit bypasses pre-commit hooks because [specific reason].
Pre-commit errors will be fixed in next commit.

Approved by: [name]"

# 3. Fix immediately:
git commit -m "Fix issues from previous emergency commit"

Never leave bypassed commits unfixed.

---

Questions?

If you're unsure whether to bypass hooks, ask first. It's better to ask than to introduce bugs into the codebase.