Skip to content
JMS Docs

Commit Guidelines

Commit Guidelines

Section titled “Commit Guidelines”

These rules are meant to keep the history clean, readable, and safe to ship. If you follow this doc, your commits will be easy to review and easy to revert.

Core Principles

Section titled “Core Principles”

  1. One commit = one logical change

    • A commit should answer one question: “What changed and why?”
    • Don’t mix unrelated work (e.g., UI polish + bug fix + refactor).

  2. Small, reviewable diffs

    • If a commit is too big to explain in one sentence, split it.
    • Large refactors should be broken into safe, mechanical steps.

  3. Clear intent in the message

    • The commit message is the headline for your change.
    • It should let someone understand the purpose without opening files.

  4. Leave things better than you found them

    • Fix small lint issues you touched, but do NOT reformat unrelated files.

Commit Message Format

Section titled “Commit Message Format”

Use this format for most commits:

<scope>: <short, imperative summary>

Examples:

  • email: fix thread refresh after reply
  • calendar: add event detail modal
  • auth: guard SSO routes on expired session
  • ui: align sidebar padding in compact mode

Rules:

  • Use imperative mood (“add”, “fix”, “remove”, “update”).
  • Keep it under ~72 characters if possible.
  • Use a clear scope: email, calendar, backend, auth, ui, etc.

When to Split Commits

Section titled “When to Split Commits”

Split if you have:

  • A refactor + a feature in the same change
  • A bug fix + unrelated CSS changes
  • Multiple files that don’t contribute to one clear goal

Example split:

  1. calendar: extract event payload helper
  2. calendar: add create event flow

When to Squash

Section titled “When to Squash”

Squash if:

  • You have multiple WIP commits (“try”, “fix again”, “oops”)
  • You made small follow-up fixes that are part of the same change

Use interactive rebase to squash:

git rebase -i HEAD~N

What Not to Commit

Section titled “What Not to Commit”
  • Secrets, API keys, credentials
  • Debug logs or console spam
  • Commented-out code
  • Temporary files or local config files

Before You Commit (Quick Checklist)

Section titled “Before You Commit (Quick Checklist)”
  • Does the change compile or run locally?
  • Did I run the relevant tests (or explain why not)?
  • Did I avoid unrelated formatting changes?
  • Is the commit message clear and scoped?
Section titled “Recommended Workflow”
  1. Review your changes:
git status -sb
  1. Stage in chunks (recommended):
git add -p
  1. Commit with a clear message:
git commit -m "scope: summary"
  1. Verify your commit:
git log -n 1

GPG Signing (If Required)

Section titled “GPG Signing (If Required)”

If signing is enabled, use:

git commit -S -m "scope: summary"

If your commit wasn’t signed, you can amend it:

git commit --amend -S --no-edit

Examples (Good vs Bad)

Section titled “Examples (Good vs Bad)”

Bad:

  • fix stuff
  • updates
  • wip

Good:

  • email: prevent duplicate replies in thread
  • calendar: show upcoming events in sidebar
  • ui: tighten spacing in inbox list

Final Notes

Section titled “Final Notes”

If you’re unsure about splitting or naming:

  • Ask a reviewer before you commit
  • Prefer smaller commits with clear scopes
  • Keep the history readable for someone new joining the project