📌 The Formula for a Good Commit Message
A commit message should be structured as follows:
<type>: <short summary> (max 50-72 chars)
<optional detailed explanation - wrap at 72 chars>
<optional: issue reference or co-authored-by>
📍 1. Use Conventional Commit Types
Start your commit message with a commit type, followed by a short summary:
| Type | Usage Example |
|---|---|
| feat | feat: add date filtering for GitHub activity |
| fix | fix: handle API failure when GitHub is down |
| refactor | refactor: optimize API response formatting |
| docs | docs: update README with API usage guide |
| chore | chore: add .gitignore and remove logs |
| style | style: format code with Black |
| test | test: add unit tests for date filtering |
📍 2. Write a Clear & Concise Summary
- Keep it within 50-72 characters.
- Use imperative mood (e.g., "Add", "Fix", "Update" instead of "Added" or "Fixes").
- Avoid unnecessary words.
✅ Good Examples
feat: add API endpoint for fetching GitHub activity
fix: resolve bug in date filtering logic
docs: update README with setup instructions
❌ Bad Examples
added new API for activity ❌ (Avoid past tense)
fixing bug in date filtering ❌ (Not in imperative form)
Updated README ❌ (Vague, what was updated?)
📍 3. Add a Detailed Description (Optional)
If the commit needs more context, add a body section:
feat: add GitHub activity API
- Fetches user events from GitHub API
- Supports filtering by single date or date range
- Caches results for faster responses
Closes #12
Use this for:
✅ Complex changes
✅ Bug fixes requiring explanation
✅ Breaking changes
📍 4. Reference Issues & PRs
If the commit is linked to an issue or pull request, reference it:
fix: resolve date filtering issue
Closes #22
OR
feat: add daily cron job for auto-fetching
Related to #15
📍 5. Use "Co-authored-by" for Team Contributions
If multiple developers worked on a commit, acknowledge them:
feat: add webhook support for GitHub activity
Co-authored-by: Edgar Gulay <[email protected]>
Co-authored-by: John Doe <[email protected]>
📍 6. Keep Commit History Clean
🚫 Avoid these commit messages:
wip: working on it ❌ (What are you working on?)
fix: bug fixes ❌ (Which bug? Be specific)
temp: test commit ❌ (Don’t commit temporary stuff)
✅ Instead, rewrite like this:
fix: correct timestamp format in API response
🚀 Bonus: Automate Commit Messages with a Git Hook
To enforce commit message rules, use a pre-commit hook:
echo 'exec < /dev/tty && git cz --hook || true' > .git/hooks/commit-msg
chmod +x .git/hooks/commit-msg
This will prompt you to enter a properly formatted message each time you commit.
💡 Summary Cheat Sheet
| ✅ Do | ❌ Don’t |
|---|---|
Use imperative tense (fix: instead of fixed:) | Use vague messages (Updated stuff) |
| Keep the summary under 72 chars | Write long, unreadable messages |
| Add a detailed body when necessary | Overload the commit summary |
| Reference issues & PRs when relevant | Leave commits unexplained |
| Use Conventional Commit types | Use generic terms like misc: |
🚀 Final Example
feat: implement GitHub activity summary API
- Fetches user events from GitHub API
- Filters activity based on date or date range
- Returns structured JSON response
Closes #1
🎯 Closing remarks: sometimes you have to let fire burn ...