Introduction

When I started planning this portfolio, one question loomed large: How do I document every change so anyone—future-me included—can follow the story of the code?
Good documentation is more than a checkbox; it’s the visible proof of discipline and craftsmanship. That realization led me straight to the humble Git commit message.

In this post I’ll share the lightweight, battle-tested convention I’m using to keep every commit concise, searchable, and self-explaining. Steal it, tweak it, or just treat it as inspiration for your own projects.

---

Why Commit Messages Matter

• Single-source timeline – Git already tracks what changed; a good message explains why.
• Effortless code reviews – Clear headers let reviewers skim; detailed bodies answer deeper questions.
• Debugging super-powers – git bisect is only magical when each commit is atomic and well-named.
• Professional credibility – Recruiters and collaborators judge repos by their commit history long before they dive into code.

---

My Commit-Message Blueprint

<type>(<optional-scope>): <short summary>

[Optional body – context, rationale, trade-offs]

[Optional footer – issue IDs, links, Co-authored-by lines]

Header Rules

• Imperative mood (e.g., “Add login route,” not “Added”).
• ≤ 50 chars for the summary; wrap longer bodies at ~72.
• The scope pinpoints the area touched (api, ci, docs).

Allowed <type> Keywords

Type	Purpose
feat	New feature
fix	Bug correction
docs	Documentation only
style	Formatting, whitespace, non-functional edits
refactor	Code restructure without feature/bug change
perf	Performance improvement
test	Adding or updating tests
chore	Build scripts, CI, dependency bumps

---

Real-World Examples

feat(vpc): add subnet routing module
docs(readme): clarify setup instructions
refactor(auth): abstract JWT validation logic
chore(deps): bump Terraform to v1.10.0

Each line tells a reader exactly what changed and where, before they even open the diff.

---

Guidelines I Live By

1. One logical change per commit – Small, focused commits are reversible and reviewable.
2. Explain why when it’s not obvious – Complex fixes deserve a few extra lines in the body.
3. Reference work items – Closes #42 keeps GitHub, GitLab, or Jira in sync.
4. Skip the noise – Never commit “lint fix” and a new feature together.

---

Anti-Patterns to Avoid

• “update stuff”, “more tweaks” – Future-you will curse past-you.
• Monster commits – 500-line diffs hide bugs and slow reviews.
• Essay-length headers – Brevity belongs in the title; details go in the body.

---

TL;DR

• Format: type(scope): summary → body → footer.
• Write in the imperative.
• Keep commits atomic.
• Document why, not just what.

By following this playbook, I’m turning my Git log into living documentation—one that proves the professionalism behind every line of code in this portfolio. Give it a try and watch your history become a narrative you’re proud to share.

Happy committing!