Commit Conventions
Commit Conventions
When you commit code, you're telling a story about what changed. We use Conventional Commits—a standardized format that makes that story easy to follow. Each commit message tells you what changed and (if needed) why.
Here's the basic structure:
<type>: <summary>
<body>
<footer>
Let's break that down:
Type - Same prefixes as branches (feat, fix, docs, etc.)
Summary - Brief description in imperative mood ("add feature" not "added feature")
Body - Longer explanation if needed (optional)
Footer - References to cards or issues (optional)
The summary is required. Everything else is optional, but helpful when your change needs explanation.
Examples
Here's what good commit messages look like in practice:
Adding a feature:
feat: add link archival endpoint
Implement POST /api/v1/links/:id/archive endpoint to allow
marking links as archived without deletion. Includes validation
and database migration.
The body explains what the feature does and what's included. Someone reading this knows exactly what to expect.
Fixing a bug:
fix: resolve popup not opening on Firefox
The popup.html failed to load on Firefox due to CSP issues.
Updated manifest.json with proper permissions.
The body explains the problem and the solution. This helps when you're debugging similar issues later.
Updating dependencies:
chore: update Docker base image to Ruby 3.4.2
Bump base image for security patches and performance improvements.
Simple documentation change:
docs: fix typo in workflow guide
For small changes, the summary is enough. No need for a body when the change is obvious.
Writing Good Commit Messages
A few simple rules make commit messages more useful:
Use imperative mood - Write "Add feature" not "Added feature" or "Adds feature"
Keep it under 50 characters - Get to the point
Capitalize the first word - "Add feature" not "add feature"
Skip the period - No need for one at the end
Use the body to explain why - The code shows how; the commit message explains why
Commit Frequency
Commit after completing logical chunks of work. Think of each commit as a checkpoint—a coherent piece of work that makes sense on its own. Small, focused commits are easier to review and easier to revert if something goes wrong.
💡 Quick tip: Not sure how to phrase your commit message? Use
/unio-commit-messageto analyze your changes and get a properly formatted suggestion. See the Cursor AI Commands page for details.
Here's what a typical work session might look like:
git commit -m "feat: add archival endpoint skeleton"
git commit -m "feat: add archival validation logic"
git commit -m "test: add archival endpoint tests"
git commit -m "docs: document archival API endpoint"
Each commit stands alone. If you need to revert the validation logic but keep the tests, you can.
Now that you're making commits, let's talk about how we use pull requests to review and merge code in the next section.