Skip to main content

Commit Message Conventions

Overview​

Clear commit messages help us understand the project's history and make it easier to track down bugs, understand features, and generate changelogs.

Format​

We follow the Conventional Commits specification:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Commit Types​

Use these types for your commits:

TypeDescriptionExample
featNew featurefeat(wishlist): add ability to share wishlists
fixBug fixfix(auth): resolve login redirect issue
docsDocumentation onlydocs(api): update authentication guide
styleCode style changes (formatting, semicolons, etc.)style(app): fix linting warnings
refactorCode change that neither fixes a bug nor adds a featurerefactor(store): simplify inventory query logic
perfPerformance improvementperf(search): optimize book search query
testAdding or updating teststest(wishlist): add unit tests for sharing
choreBuild process or auxiliary tool changeschore(deps): update dependencies
ciCI configuration changesci(github): add automated deployment
buildChanges to build system or dependenciesbuild(flutter): upgrade to Flutter 3.32
revertRevert a previous commitrevert: feat(wishlist): add sharing

Scopes​

Scopes indicate what part of the codebase is affected:

App (Flutter)​

  • auth - Authentication and user management
  • wishlist - Wishlist features
  • inventory - Store inventory management
  • pos - Point of sale features
  • social - Social features (follows, reviews, etc.)
  • cart - Shopping cart
  • search - Search functionality
  • ui - General UI components

Backend​

  • api - API endpoints
  • db - Database schema or migrations
  • auth - Authentication services
  • email - Email services
  • payment - Payment processing
  • jobs - Background jobs

General​

  • deps - Dependencies
  • config - Configuration files
  • docs - Documentation

Writing Good Descriptions​

Do's​

✅ Use imperative mood ("add" not "added" or "adds")

feat(wishlist): add export functionality

✅ Be concise but descriptive

fix(auth): prevent duplicate user registration

✅ Reference issues when relevant

fix(search): resolve timeout on large catalogs (fixes #123)

Don'ts​

❌ Don't use past tense

feat(wishlist): added export functionality  // wrong

❌ Don't be vague

fix: various fixes  // wrong

❌ Don't include unnecessary details in subject

feat(wishlist): add export functionality by creating new service layer with CSV generation  // too long

Examples​

Feature Addition​

feat(wishlist): add ability to share wishlists

Users can now generate a shareable link for their wishlists.
The link allows read-only access to anyone with the URL.

Closes #456

Bug Fix​

fix(auth): resolve login redirect loop

Fixed an issue where users would be stuck in a redirect loop
after logging in if they had special characters in their username.

The issue was caused by improper URL encoding in the redirect parameter.

Fixes #789

Refactoring​

refactor(inventory): simplify stock check logic

Consolidated three separate stock checking methods into one
reusable utility function. No behavior changes.

Documentation​

docs(api): update wishlist API examples

Added examples for the new wishlist sharing endpoints.
Updated error response documentation.

Breaking Changes​

For breaking changes, add BREAKING CHANGE: in the footer:

feat(api): change wishlist response format

Updated the wishlist API to return items in a more structured format.

BREAKING CHANGE: The wishlist response now nests items under a `data` key.
Clients must update to access `response.data.items` instead of `response.items`.

Multi-line Commits​

For complex changes, use the body to provide context:

feat(pos): implement offline mode support

Add ability for POS system to function without internet connection.
Transactions are queued locally and synced when connection is restored.

- Queue transactions in IndexedDB
- Sync on reconnection
- Show sync status indicator
- Handle conflict resolution

Closes #234, #567

Special Cases​

Work in Progress​

wip(feature): partial implementation of X

This is a work-in-progress commit. The feature is not complete.

Note: WIP commits should generally not be pushed to main branches.

Reverting Commits​

revert: feat(wishlist): add sharing feature

This reverts commit abc123def456.

The feature caused performance issues in production and needs
to be redesigned. Will be reintroduced in a future PR.

Tools​

Commitlint​

The project uses commitlint to enforce these conventions:

# Install commitlint
npm install --save-dev @commitlint/cli @commitlint/config-conventional

# Commits that don't follow conventions will be rejected
git commit -m "bad commit message"  # ❌ Fails
git commit -m "feat(wishlist): add export"  # ✅ Passes

Git Hooks​

We use Husky to run commitlint automatically:

# The commit hook runs automatically
git commit -m "your message"

Benefits​

Following these conventions enables:

  1. Automatic changelog generation
  2. Better git history readability
  3. Semantic versioning automation
  4. Easier debugging - Find when features were added or bugs were fixed
  5. Clear communication - Team members understand changes at a glance

References​