diff --git a/.gitmessage.txt b/.gitmessage.txt new file mode 100644 index 000000000..4b97b59d0 --- /dev/null +++ b/.gitmessage.txt @@ -0,0 +1,47 @@ +# SAMO-DL Commit Message Template +# +# Quick setup: +# git config commit.template .gitmessage.txt +# # To make it global: git config --global commit.template "$(pwd)/.gitmessage.txt" +# +# Format: ()!: +# (scope is optional; add "!" for breaking changes) +# Body: explain what and why, wrapped at ~72 chars per line +# Footer: references and BREAKING CHANGE notes +# +# Types: +# feat: A new feature +# fix: A bug fix +# docs: Documentation only changes +# style: Formatting, whitespace, missing semicolons, no code change +# refactor: Code change that neither fixes a bug nor adds a feature +# perf: A code change that improves performance +# test: Adding missing tests or correcting existing tests +# build: Changes to build system or external dependencies +# ci: Changes to CI configuration files and scripts +# chore: Other changes that don't modify src or test files +# revert: Reverts a previous commit +# +# Rules: +# - ONE purpose per commit (no "and", "also", "plus") +# - Subject line ≤ 50 characters +# - Use imperative mood ("Add" not "Added") +# - No period at end of subject line +# - Wrap body at ~72 characters per line +# - Reference issues/PRs in footer (e.g., "Closes #123") +# - Use "BREAKING CHANGE: ..." in footer for breaking changes +# +# Examples: +# feat(auth): add login with email magic links +# fix(loader): resolve memory leak in model loading +# perf(infer): cache tokenizer to reduce setup time +# refactor(rate-limit): simplify token bucket logic +# docs(api): update inference usage examples +# style: run formatter across repo +# build: bump torch to 2.4.x +# ci: parallelize test matrix +# revert: revert "feat(auth): add magic links" +# feat(core)!: switch default precision to bfloat16 +# BREAKING CHANGE: default precision is now bfloat16; set +# SAMO_PRECISION=float32 to keep previous behavior. +# Closes #174 diff --git a/CODE_QUALITY_README.md b/CODE_QUALITY_README.md new file mode 100644 index 000000000..8bf49a0cb --- /dev/null +++ b/CODE_QUALITY_README.md @@ -0,0 +1,209 @@ +# SAMO-DL Code Quality Standards + +## 🎯 Mission: Prevent Monster PRs Forever + +This document outlines the **strict rules** and **automated enforcement** designed to prevent the creation of massive, unfocused pull requests that slow down development and make code reviews impossible. + +## 🚫 THE PROBLEM WE SOLVE + +**Monster PRs** are pull requests that: +- Change 100+ files +- Add 1000+ lines of code +- Mix multiple concerns (API + tests + docs + infrastructure) +- Take weeks to review +- Cause merge conflicts +- Block progress + +## ✅ THE SOLUTION: Micro-PRs Only + +### **Hard Limits (Automated Enforcement)** +```yaml +# GitHub Actions - PR Size Guard +max_files_changed: 50 # HARD STOP at 50 files +max_lines_changed: 1500 # HARD STOP at 1500 lines +max_commits_per_pr: 5 # HARD STOP at 5 commits +branch_lifetime: 72h # Auto-close or require split after 72h (extensions available for complex changes) +``` + +#### Requirement: PR purpose must be exactly one sentence +- ✅ "Add user authentication system" +- ✅ "Fix memory leak in model loading" +- ❌ "Improve model architecture and fix bugs" *(TWO THINGS!)* +- ❌ "Refactor training pipeline" *(TOO VAGUE!)* + +## 🛠️ AUTOMATED ENFORCEMENT + +### **1. Local Hooks (pre-commit + commit-msg)** +Use the pre-commit framework (versioned via `.pre-commit-config.yaml`) to run format/lint/type/security checks on staged files. Enforce commit message format via a `commit-msg` hook (e.g., Commitizen). + +**Notes:** +- Branch naming and "single purpose" are enforced in CI (see PR Scope Checker), not locally. +- Hooks run automatically once installed (`pre-commit install` and `pre-commit install --hook-type commit-msg`). + +### **2. PR Scope Checker** +```bash +python scripts/check_pr_scope.py --strict +``` +> **Note:** The PR scope checker script is available in the repository and actively maintained. +Validates: +- File count ≤ 50 +- Line changes ≤ 1500 +- Single purpose (no mixing concerns) +- Branch naming compliance + +### **3. CI Pipeline Checks** +GitHub Actions automatically: +- Runs scope validation on PR creation +- Fails builds that exceed limits +- Prevents merging of out-of-scope PRs + +## 📋 DEVELOPMENT WORKFLOW + +### **Before Creating a Branch** +```md +# Answer these questions: +1. Can I describe this in ONE sentence? +2. Will this affect < 50 files? +3. Can I complete this in < 4 hours? +4. Is this EXACTLY ONE concern? +5. Am I mixing API + tests + docs? + +# If ANY answer is NO: Split into separate PRs +``` + +### **Branch Naming Convention** +```text +feat/short-description # New features +fix/short-description # Bug fixes +chore/short-description # Build/tooling changes +refactor/short-description # Code restructuring +docs/short-description # Documentation +test/short-description # Test additions +``` + +**Examples:** +- ✅ `feat/add-user-auth` +- ✅ `fix/validate-input` +- ✅ `chore/update-deps` +- ✅ `refactor/simplify-logic` +- ❌ `feat/add-auth-and-fix-bugs` *(multiple concerns)* +- ❌ `fix-stuff` *(too vague)* + +### **Commit Message Format** +```gitcommit +(): + + +``` +**Examples:** +```gitcommit +feat: add JWT token authentication +fix: resolve memory leak in model loading +chore: update Python dependencies +refactor: simplify rate limiter logic +``` + +## 🏗️ CODE QUALITY TOOLS + +### **Automated Tools** +- **Ruff**: Ultra-fast code formatting, linting, and import sorting (replaces Black, isort, flake8) +- **pylint**: Advanced code analysis +- **mypy**: Type checking +- **bandit**: Security scanning +- **safety**: Dependency vulnerability checks + +### **Pre-commit Hooks** +Run automatically on commit: +```bash +pre-commit install # Install hooks +pre-commit run --all-files # Run on all files +``` + +### **Development Commands** +```bash +make format # Format code +make lint # Run linters +make test # Run tests +make quality-check # Run all quality checks +``` + +## 🚨 EMERGENCY OVERRIDES + +**Only for critical production issues:** +```yaml +override_label: "EMERGENCY-OVERRIDE" +required_approvers: 2 +max_override_per_week: 1 +auto_close_after: 8h +``` + +> **Note:** Overrides require label + 2 approvers + admin "bypass PR requirements" permission, or a temporary policy change. GitHub cannot bypass required checks by workflow alone. + +## 📊 SUCCESS METRICS + +**Weekly Tracking:** +- Average PR size: < 15 files +- PR lifetime: < 24 hours +- Number of scope violations: 0 +- Merge conflicts: < 1 per week + +**Red Flags (Auto-alert):** +- Any PR > 50 files +- Any branch > 48 hours old +- Any PR title with "and", "also", "plus" +- Any PR summary > 2 sentences (detailed descriptions in body are encouraged) + +## 🎯 WHY THIS WORKS + +### **Psychological Benefits** +- **Small wins**: Frequent merges build momentum +- **Fast feedback**: Quick reviews = faster iteration +- **Reduced risk**: Smaller changes = easier rollback +- **Team satisfaction**: Actually shipping features + +### **Technical Benefits** +- **Fewer merge conflicts**: Smaller, focused changes +- **Easier reviews**: 50 files vs 100+ files +- **Better testing**: Isolated changes = targeted tests +- **Faster CI/CD**: Smaller PRs = faster pipelines + +## 🚀 IMPLEMENTATION + +### **Immediate Actions** +1. **Install pre-commit hooks**: `pre-commit install` +2. **Set commit template**: `git config commit.template .gitmessage.txt` + > **Note:** The `.gitmessage.txt` file is included in the repository with a comprehensive commit message template following Conventional Commits standards. +3. **Run scope checker**: `python scripts/check_pr_scope.py` +4. **Review existing PRs**: Close any that violate rules + +### **Team Adoption** +1. **Training session**: Walk through the rules +2. **Documentation**: Share this guide +3. **Examples**: Show good vs bad PR examples +4. **Celebrate**: Recognize teams following the rules + +## 📞 SUPPORT + +**Questions?** Ask in the development channel. + +**Found a violation?** Use the PR comment template: +```md +🚨 **SCOPE VIOLATION DETECTED** +This PR exceeds our size limits: +- Files: [count]/50 max +- Lines: [count]/1500 max +- Multiple concerns: [list them] + +Please split into focused micro-PRs. +``` + +--- + +## 🎉 CONCLUSION + +### Summary +Small PRs = Fast reviews = Quick merges = Happy developers = Successful project + +**NO EXCEPTIONS. NO EXCUSES. NO "JUST THIS ONCE".** + +Welcome to the era of **productive, focused development!** 🚀