Mastering Conventional Commits

If you’ve ever looked at a messy Git history full of messages like “fixed stuff”, “update”, or “changes”, you already know why Conventional Commits exist. This simple, standardized way of writing commit messages makes your project history readable, and searchable.

This blog will teach you, in a beginner-friendly way, about Conventional Commits with real examples from different scenarios.

1. Why Conventional Commits Matter (The “Why” Before the “How”)

Imagine opening a project you haven’t touched in 6 months. You run git log and see:

• added stuff

• fix bug

• update

Now imagine seeing instead:

• feat(auth): add Google OAuth login

• fix(mentorship): prevent duplicate milestone submissions

• refactor(api): extract validation logic into middleware

Which one lets you understand the project’s story in 30 seconds? That’s the power of Conventional Commits.

Benefits you’ll feel immediately:

1. Your teammates (and future you) can scan history in seconds

2. Tools can automatically generate changelogs and bump versions

3. Code reviews become faster

4. You look professional

2. The Basic Structure (Memorize This)

type(scope): short summary

[optional body with more details]

Real example:

feat(membership): improve workflow, permissions, and session reporting

Breakdown:

• feat → the type

• (membership) → the scope (optional but powerful)

• improve workflow... → the summary

3. Step-by-Step: How to Actually Write One

Step 1: Ask yourself “What did I change?”

This is the most important question. Be honest with yourself.

What changed?	Type to use
New feature or functionality	feat
Bug fix	fix
Code restructuring (no behavior change)	refactor
Performance improvement	perf
Documentation only	docs
Formatting / whitespace / UI (no logic)	style
Adding or updating tests	test
Maintenance, configs, dependencies	chore

Pro tip: If you’re unsure, ask:
“Did I add new user-facing behavior?” → feat
“Did I fix something that was broken?” → fix

Step 2: Write the Summary (The Hardest Part for Beginners)

Rules (follow these religiously):

• Use present tense (“add”, “fix”, “improve” — not “added”, “fixed”)

• Keep it short (ideally under 72 characters)

• Describe what changed, not how you did it

• Start with a verb

Good examples:

feat: add mentor session reporting
fix: prevent editing of registration certificate
refactor: extract validation into separate service
perf: reduce API response time by 40%

Bad examples (and why):

feat: added a feature where mentors can now submit reports   # past tense + too long
fix: fixed bug                                               # too vague
update: changed some files                                   # wrong type + vague

Step 3: Add a Scope When It Makes Sense

Use (scope) when your project has clear modules.

Examples from different projects:

feat(auth): add password reset flow
fix(mentorship): enforce mentor review before funding release
refactor(api/users): simplify user profile endpoint
perf(db): optimize mentor search query
docs(readme): update installation instructions
style(frontend): standardize button padding
test(mentorship): add tests for session report submission
chore(deps): upgrade React to 18.3

Step 4: Add a Body When Changes Are Complex

If you changed multiple things, use a body with bullet points.

feat(mentorship): improve workflow, permissions, and session reporting

- require mentorship registration before any funding
- move milestone reviews from admin to mentors
- allow mentors to submit session reports
- add permission checks for entrepreneurs editing certificates

4. Decision Logic — Your Personal Flowchart

Every time you’re about to commit, run through this in your head:

1. What type of change is this?
   (Use the table above)

2. What is the outcome of this change?
   (Write this as the summary)

3. Which part of the project is affected?
   (Add as scope if helpful)

4. Is this complex enough to need a body?
   (Usually yes if more than 1 logical changed)

5. Practice Examples from Multiple Real Scenarios

Scenario 1: E-commerce Web App

feat(cart): add quantity selector with stock validation
fix(checkout): prevent duplicate order submissions on slow network
refactor(products): extract price calculation into reusable hook
perf(api): cache product search results for 5 minutes

Scenario 2: Mobile App (React Native)

feat(onboarding): add progress indicator on 4-step flow
fix(auth): handle expired token refresh correctly on iOS
style(components): make all buttons use consistent height
test(profile): add unit tests for avatar upload

Scenario 3: Data / Backend Project

feat(etl): add daily revenue aggregation job
fix(db): handle null values in user analytics query
perf(queries): add index on mentorship_sessions.created_at
chore(deps): bump pandas from 2.1 to 2.2

Scenario 4: Documentation & Maintenance

docs(api): document new mentorship endpoints
style: run prettier across entire frontend
chore(ci): add automated lint check on pull requests

6. Common Mistakes Beginners Make (and How to Avoid Them)

Mistake	Wrong	Correct
Past tense	added new login	add Google OAuth login
Too vague	fix bug	fix: prevent duplicate registrations
Explaining implementation	use useEffect to fetch data	fetch user data on component mount
Using wrong type	update: change button color	style: standardize button colors
Forgetting scope when helpful	feat: improve dashboard	feat(dashboard): improve layout

7. Quick Reference Card

type(scope): summary in present tense

Body (optional):
- bullet point 1
- bullet point 2

Footer (optional):
BREAKING CHANGE: description
Closes #123

The fastest way to internalize this is practice with real changes.

Final Words

Conventional Commits are not about being perfect. They’re about being consistent and clear. Start using them on your next 10 commits and you’ll already feel the difference.

You don’t have to change everything overnight. Just pick one rule today:

“I will always start my commit with feat: or fix: and write in present tense.”