feat: add commit message best practices

2026-01-15 12:02:25 +01:00
parent 25077cd589
commit 74a23dbbca
1 changed files with 123 additions and 0 deletions
--- a/COMMIT-MESSAGES.md
+++ b/COMMIT-MESSAGES.md
@@ -0,0 +1,123 @@
+# Writing Good Commit Messages
+
+A good commit message explains **what** the change does and **why** it matters. Your future self (and your teammates) will thank you.
+
+## The Golden Rule: Write the Intent
+
+Write your message as a command - what will this commit **do** when applied?
+
+**Good (imperative, present tense):**
+```
+Add login button to navbar
+Fix crash when username is empty
+Remove unused database connection
+```
+
+**Avoid (past tense, describing what you did):**
+```
+Added login button to navbar
+Fixed crash when username is empty
+Removed unused database connection
+```
+
+**Why?** Think of it as completing this sentence:
+> "If applied, this commit will... **add login button to navbar**"
+
+## Use Prefixes to Categorize
+
+Start your message with a prefix that tells readers what kind of change this is:
+
+| Prefix | Use For | Example |
+|--------|---------|---------|
+| `feat:` | New features | `feat: add password reset flow` |
+| `fix:` | Bug fixes | `fix: prevent duplicate form submission` |
+| `docs:` | Documentation only | `docs: add API examples to README` |
+| `style:` | Formatting, no code change | `style: fix indentation in auth module` |
+| `refactor:` | Code change that doesn't fix or add | `refactor: extract validation logic` |
+| `test:` | Adding or fixing tests | `test: add unit tests for login` |
+| `chore:` | Maintenance, dependencies | `chore: update pytest to 8.0` |
+
+## Keep It Short
+
+The first line should be **50 characters or less**. This ensures it displays properly in:
+- Git log output
+- GitHub/Azure DevOps commit lists
+- Email notifications
+
+```
+fix: resolve memory leak in image processing
+│                                            │
+└──────────── 45 characters ─────────────────┘
+```
+
+## Add Details When Needed
+
+For complex changes, add a blank line and then more context:
+
+```
+fix: prevent crash when user uploads empty file
+
+The application crashed because we tried to read the first byte
+of an empty file. Now we check file size before processing.
+
+Closes #142
+```
+
+Use the body to explain:
+- **Why** this change was necessary
+- **What** was the problem or context
+- **How** does this approach solve it (if not obvious)
+
+## Examples
+
+**Simple bug fix:**
+```
+fix: correct tax calculation for EU customers
+```
+
+**New feature:**
+```
+feat: add dark mode toggle to settings
+```
+
+**With context:**
+```
+refactor: split user service into smaller modules
+
+The user service had grown to 800 lines and was handling
+authentication, profile management, and notifications.
+Split into three focused modules for maintainability.
+```
+
+**Documentation:**
+```
+docs: add setup instructions for Windows
+```
+
+## Quick Reference
+
+```
+<prefix>: <what this commit does>
+
+[optional body: why and how]
+
+[optional footer: references issues]
+```
+
+**Checklist:**
+- [ ] Starts with a prefix (`feat:`, `fix:`, etc.)
+- [ ] Uses imperative mood ("add" not "added")
+- [ ] First line under 50 characters
+- [ ] Explains why, not just what (for complex changes)
+
+## Common Mistakes
+
+| Instead of... | Write... |
+|---------------|----------|
+| `fixed bug` | `fix: prevent null pointer in search` |
+| `updates` | `feat: add email notifications` |
+| `WIP` | `feat: add basic form validation` |
+| `stuff` | `chore: clean up unused imports` |
+| `fix: fix the bug` | `fix: handle empty input in calculator` |
+
+Your commit history tells the story of your project. Make it a story worth reading.