# 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:

```bash
# 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:**

```bash
# 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.