Commit Conventions¶

Last Updated: 2025-01-22

Commit message conventions based on Conventional Commits for AccessALI.

Overview¶

Consistent commit messages:

Enable automated changelog - Generate release notes automatically
Improve readability - Clear git history
Facilitate searching - Find specific changes easily
Support versioning - Determine version bumps (SemVer)

Format¶

Basic Structure¶

type(scope): subject

body

footer

Example¶

feat(dashboard): add property search functionality

Implemented real-time search with debouncing for property lookup.
Returns top 3 results matching brand, project name, or unit number.

Closes #45

Type¶

Required Types¶

Type	Description	Version Bump
`feat`	New feature	Minor
`fix`	Bug fix	Patch
`docs`	Documentation only	None
`style`	Code style (formatting, whitespace)	None
`refactor`	Code restructuring (no feature/bug)	None
`perf`	Performance improvement	Patch
`test`	Adding or updating tests	None
`chore`	Maintenance tasks	None
`ci`	CI/CD changes	None
`build`	Build system changes	None
`revert`	Revert previous commit	Patch

Breaking Changes¶

Add ! after type/scope for breaking changes:

feat(api)!: change authentication response format

BREAKING CHANGE: The authentication endpoint now returns a different
response format. Update clients to handle the new structure.

Scope¶

Scope indicates the area of change:

Common Scopes¶

Scope	Description
`dashboard`	Dashboard page and features
`auth`	Authentication and authorization
`property`	Property-related features
`milestone`	Milestone tracking
`api`	API routes and endpoints
`repository`	Repository layer
`use-case`	Use case layer
`component`	UI components
`database`	Database schema and migrations
`docker`	Docker configuration
`ci`	CI/CD pipeline
`deps`	Dependencies

Examples¶

feat(dashboard): add user profile section
fix(auth): correct email validation regex
docs(api): update server actions documentation
refactor(repository): simplify query logic
test(use-case): add dashboard use case tests
chore(deps): update next to 15.5.6

Subject¶

The subject line should:

Use imperative mood ("add" not "added" or "adds")
Not capitalize first letter
Not end with a period
Be 50 characters or less

# Good
feat(dashboard): add property search
fix(auth): correct token expiration
docs: update installation guide

# Bad
feat(dashboard): Added property search.
fix(auth): Corrects token expiration
docs: Updated the installation guide.

Body¶

The body should:

Provide context and motivation
Explain what and why (not how)
Use imperative mood
Wrap at 72 characters
Be separated from subject by blank line

feat(dashboard): add property search functionality

The dashboard now includes a search bar that allows users to quickly
find their properties by brand, project name, or unit number.

The search is debounced (300ms) to prevent excessive server requests
and returns a maximum of 3 results for quick navigation.

This addresses the issue where users with multiple properties had
difficulty locating specific units.

The footer should include:

Issue references: Closes #123, Fixes #456, Refs #789
Breaking changes: BREAKING CHANGE: description
Co-authors: Co-authored-by: Name <email>

feat(api): add pagination to properties endpoint

Add limit and offset query parameters to the properties API endpoint
to support pagination for users with many properties.

BREAKING CHANGE: The properties endpoint now returns paginated results
by default. Use limit=-1 to get all results (not recommended).

Closes #123
Refs #456

Examples¶

Feature¶

feat(milestone): add progress tracking

Implement progress tracking for construction milestones.
Users can now see percentage complete for each milestone phase.

- Added progress field to Milestone model
- Created updateMilestoneProgress repository function
- Added progress bar component
- Implemented real-time updates

Closes #45

Bug Fix¶

fix(auth): correct session expiration handling

Fix issue where sessions were expiring prematurely due to
incorrect token refresh logic.

The token refresh was using the wrong timestamp comparison,
causing valid sessions to be marked as expired.

Fixes #78

Documentation¶

docs(api): add server actions documentation

Add comprehensive documentation for server actions including:
- Authentication patterns
- Error handling
- Form handling examples
- Testing strategies

Closes #92

Refactoring¶

refactor(repository): extract common query logic

Extract repeated query patterns into reusable helper functions
to reduce code duplication across repositories.

No functional changes.

Performance¶

perf(dashboard): optimize property data loading

Reduce dashboard load time by 60% through:
- Parallel data fetching with Promise.all
- Selecting only required fields
- Implementing response caching

Before: 800ms average
After: 320ms average

Breaking Change¶

feat(api)!: update authentication response format

Change authentication endpoint response to include additional
user metadata and standardize error responses.

BREAKING CHANGE: The /api/auth/login endpoint now returns:
{
  user: { id, email, name },
  token: string,
  expiresAt: number
}

Previously returned:
{
  token: string
}

Update all API clients to handle the new format.

Closes #156

Commit Message Template¶

Create .gitmessage in project root:

# type(scope): subject (max 50 chars)

# body: explain what and why (wrap at 72 chars)

# footer: issue references, breaking changes

# Types:
#   feat:     New feature
#   fix:      Bug fix
#   docs:     Documentation only
#   style:    Code style (formatting, whitespace)
#   refactor: Code restructuring
#   perf:     Performance improvement
#   test:     Adding/updating tests
#   chore:    Maintenance tasks
#   ci:       CI/CD changes
#
# Examples:
#   feat(dashboard): add property search
#   fix(auth): correct token expiration
#   docs: update installation guide
#
# Breaking changes: add ! after type/scope
#   feat(api)!: change response format

Configure git to use template:

git config commit.template .gitmessage

Tools¶

Commitizen¶

Interactive commit message helper:

# Install
npm install -g commitizen cz-conventional-changelog

# Configure
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

# Use
git cz

Commitlint¶

Enforce commit message format:

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

# Configure
echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js

# Add husky hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

Best Practices¶

Do

Write clear, descriptive messages
Use present tense, imperative mood
Reference issues in footer
Keep subject line short (≤50 chars)
Explain why, not how
Use scope to indicate area
Commit early and often
Make atomic commits

Don't

Write vague messages ("fix stuff", "updates")
Commit unrelated changes together
Include WIP commits in main branch
Use past tense ("added", "fixed")
Skip commit type/scope
Exceed character limits
Commit broken code
Forget issue references

Atomic Commits¶

Each commit should:

Represent a single logical change
Be independently deployable
Not break tests
Have a clear purpose

# Bad: Multiple concerns in one commit
git commit -m "feat: add search, fix auth, update docs"

# Good: Separate atomic commits
git commit -m "feat(dashboard): add property search"
git commit -m "fix(auth): correct token expiration"
git commit -m "docs(api): update authentication guide"

Interactive Rebase¶

Clean up commits before pushing:

# Rebase last 3 commits
git rebase -i HEAD~3

# In editor:
# - pick: keep commit
# - reword: change message
# - squash: combine with previous
# - fixup: combine, discard message
# - drop: remove commit

References¶

Next Steps¶

Review Code Review Guidelines
Set up commit message template
Install commitlint (optional)
Practice writing good commit messages

Commit Conventions¶

Overview¶

Format¶

Basic Structure¶

Example¶

Type¶

Required Types¶

Breaking Changes¶

Scope¶

Common Scopes¶

Examples¶

Subject¶

Body¶

Footer¶

Examples¶

Feature¶

Bug Fix¶

Documentation¶

Refactoring¶

Performance¶

Breaking Change¶

Commit Message Template¶

Tools¶

Commitizen¶

Commitlint¶

Best Practices¶

Atomic Commits¶

Interactive Rebase¶

Related Documentation¶

References¶

Next Steps¶