Commit Etiquette: Blah Blah—What’s the Convention?

When it comes to committing code, it’s a bit like making sure your outfit is both functional and fashionable for the day. Sure, your code works, but if your commits are a mess, it’s like turning up in pyjamas to a client meeting—no one wants that.

Why Commit Messages Matter

Imagine reading through your codebase in a few months—or worse, someone else doing it. Without clear, concise commit messages, you’re doomed to endless “What was I thinking?” moments. Good commits are like leaving breadcrumbs so you or anyone else can navigate the changes without falling into a rabbit hole of confusion.

The Art of Commit Messages

1. Be Brief, Yet Descriptive:

A commit message should read like a well-crafted headline. No one needs the whole story here—just the gist. For example:

✅ Good: Fix layout alignment issue on mobile

❌ Bad: Fixed some issues, probably layout, I think

2. Capitalise Your First Word:

It’s a little thing, but so is wearing matching socks. Capitalising the first word of your commit shows attention to detail. It looks cleaner and more professional.

3. Use the Imperative Mood:

Commit messages should sound like commands.

• Example: Add new login button, not Added new login button or Adding new login button.

It’s like writing a to-do list for your repo: “Do this,” “Fix that,” “Implement this feature.”

4. Group Related Changes:

Avoid bundling unrelated changes into one commit. Small, focused commits make rolling back easier and debugging less of a nightmare.

Feat: The Magic Word

Ever wondered what the deal is with “feat”? It’s not just fancy jargon; it’s part of conventional commits. Use it to label new features. Conventional commits follow a structure like:

• feat: Introducing a new feature. Example: feat: add dark mode toggle
• fix: A bug fix. Example: fix: correct alignment issue on mobile
• refactor: Code changes that neither fix a bug nor add a feature, typically improving the code structure. Example: refactor: move utility functions to helpers directory
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.). Example: style: apply consistent spacing in CSS
• chore: Routine tasks or updating dependencies. Example: chore: update npm dependencies
• perf: Performance improvements. Example: perf: improve rendering speed of the dashboard
• test: Adding or updating tests. Example: test: add unit tests for login component
• docs: Documentation changes. Example: docs: update README with setup instructions
• build: Changes that affect the build system or external dependencies (e.g., Gulp, Webpack, NPM). Example: build: update webpack config for production
• ci: Continuous integration changes (e.g., CircleCI, GitHub Actions configurations). Example: ci: add automated test runner to CI pipeline
• revert: Reverting a previous commit. Example: revert: revert commit abc123 due to regression
• env: Changes related to environment variables or configurations. Example: env: add staging environment variables
• security: Security-related improvements or fixes. Example: security: fix SQL injection vulnerability
• deps: Updates or changes to dependencies (some prefer using this instead of chore for dependency updates). Example: deps: update react and react-dom to v17

Best Practices for the Perfect Commit

• Commit Often, but Meaningfully: Commit regularly to save progress, but ensure each commit has a point.
• Ensure Atomicity: Each commit should ideally focus on one thing. One commit = one logical change.
• Ensure Atomicity: Each commit should ideally focus on one thing. One commit = one logical change.