10k-experts-platform

Commit Policy - 100% Error-Free GitHub Repository

🎯 Core Policy

Before ANY commit reaches GitHub, ALL verification checks MUST pass with ZERO errors.

This policy ensures our main branch remains pristine, production-ready, and fully functional at all times.

📋 Pre-Commit Verification Requirements

✅ Required Checks (All Must Pass)

  1. Dependency Verification
    • Node.js version 18.x or 20.x
    • npm version 9.x or higher
    • All dependencies installed correctly
  2. Backend Quality Gates
    • ✅ Prisma schema validation
    • ✅ Prisma Client generation successful
    • ✅ ESLint passes with 0 errors
    • ✅ All unit tests passing (17/17 currently)
    • ✅ Integration tests passing or explicitly disabled
    • ✅ Contract tests passing or explicitly disabled
    • ✅ TypeScript compilation successful (where applicable)
  3. Frontend Quality Gates
    • ✅ ESLint passes with 0 errors (warnings allowed within threshold)
    • ✅ TypeScript compilation successful
    • ✅ Production build completes successfully
    • ✅ No bundle size regressions
  4. Git Hygiene
    • ✅ No merge conflicts
    • ✅ No unstaged package-lock.json changes
    • ✅ No .env files staged for commit
    • ✅ No debug console.log statements in staged code
  5. Security
    • ✅ No high-severity npm vulnerabilities
    • ✅ No secrets or credentials in code
    • ✅ Webhook signatures validated (where applicable)

🚀 How to Use Pre-Commit Verification

Windows (PowerShell)

.\scripts\pre-commit-check.ps1

Linux/Mac (Bash)

./scripts/pre-commit-check.sh

Expected Output

╔════════════════════════════════════════════════════════════════╗
║                  ✅ ALL CHECKS PASSED ✅                       ║
║                                                                ║
║            Safe to commit to GitHub!                           ║
╚════════════════════════════════════════════════════════════════╝

Next steps:
  1. git add .
  2. git commit -m "your message"
  3. git push origin your-branch

⛔ What Happens if Checks Fail?

If ANY check fails, you will see:

╔════════════════════════════════════════════════════════════════╗
║                  ❌ VERIFICATION FAILED ❌                     ║
║                                                                ║
║     N check(s) failed. Fix errors before committing!          ║
╚════════════════════════════════════════════════════════════════╝

ACTION REQUIRED:

  1. Review the failed check output
  2. Fix all errors
  3. Re-run the verification script
  4. Only commit when ALL checks pass

🔄 Development Workflow

Standard Workflow

1. Make code changes
2. Test locally
3. Run: .\scripts\pre-commit-check.ps1
4. Fix any errors if checks fail
5. Re-run verification until all pass
6. git add .
7. git commit -m "descriptive message"
8. git push origin branch-name

Feature Branch Workflow

1. Create feature branch: git checkout -b feature/your-feature
2. Develop and commit following standard workflow
3. Before creating PR:
   - Run pre-commit verification
   - Ensure all checks pass
4. Create Pull Request
5. GitHub Actions CI/CD runs automatically
6. Address any CI/CD failures
7. Merge only when CI/CD passes

📊 Current Test Status

As of 2025-11-01:

Component Tests Status Notes
Backend Unit Tests 17/17 ✅ PASSING 100% passing
Backend Integration Tests 0 active ⚠️ DISABLED Temporarily disabled (Prisma type issues)
Backend Contract Tests N/A ℹ️ PLACEHOLDER To be implemented
Frontend Build - ✅ PASSING 325.48 kB bundle
Frontend Lint - ✅ PASSING 0 errors, 92 warnings (acceptable)

🛡️ Why This Policy?

Benefits

  1. Production Stability: Main branch is always deployable
  2. Team Confidence: Everyone can trust the codebase state
  3. Faster Debugging: Errors caught before they reach shared branches
  4. Better Code Review: Reviewers focus on logic, not syntax errors
  5. CI/CD Efficiency: Fewer failed pipeline runs
  6. Professional Standards: Industry best practices

Anti-Patterns to Avoid

❌ “I’ll fix it in the next commit” ❌ “It’s just a small error” ❌ “The tests pass locally, so it’s fine” ❌ “I’ll let CI/CD catch it” ❌ Committing with failing tests ❌ Skipping verification checks

🔧 Troubleshooting Common Issues

Issue: Prisma Client errors

cd backend
npx prisma generate

Issue: ESLint errors

cd backend  # or frontend
npm run lint -- --fix

Issue: Test failures

cd backend
npm run test:unit
# Review and fix failing tests

Issue: Build failures

cd frontend
npm run build
# Check TypeScript errors
npx tsc --noEmit

📝 Exceptions

There are NO exceptions to this policy.

If you believe you have a valid reason to bypass verification:

  1. Discuss with team lead
  2. Document the exceptional circumstance
  3. Create a tracked issue to address post-commit
  4. Must still pass CI/CD on GitHub

🎓 Training Resources

📞 Support

If you encounter issues with the verification script:

  1. Check this documentation
  2. Review error messages carefully
  3. Consult team members
  4. Update this document if you find solutions to common problems

Remember: A few extra minutes of verification saves hours of debugging later!

Last Updated: 2025-11-01 Version: 1.0