Documentation

adrs/054-commit-message-guidelines.md

ADR-054: Commit Message Guidelines and Conventions

Status

Proposed

Context

The Acsis Core repository has multiple contributors—both human developers and AI agents—working on various components simultaneously. Clear, consistent commit messages are essential for:

Communication Challenges

  1. Traceability: Linking commits to issues for understanding why changes were made
  2. Code Review: Reviewers need context to evaluate changes effectively
  3. Git History: git log, git blame, and git bisect require meaningful messages
  4. Changelog Generation: Potential future automation depends on structured messages
  5. Attribution: AI-assisted development requires clear co-authorship indication
  6. Team Coordination: Multiple agents may work on related code; clear commits help avoid conflicts

Industry Context

Conventional Commits is a widely-adopted specification that adds structure to commit messages while remaining human-readable. It provides a lightweight convention that works well with semantic versioning and automated tooling.

Decision

We adopt Conventional Commits with project-specific extensions for Linear integration and AI co-authorship.

Commit Message Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

Type Description Example
feat New feature or functionality feat(catalog): add batch import endpoint
fix Bug fix fix(prism): resolve passport lookup race condition
docs Documentation only docs: add ADR-053 commit guidelines
refactor Code change that neither fixes a bug nor adds a feature refactor(identity): simplify token validation
test Adding or correcting tests test(transport): add shipment cancellation tests
chore Maintenance tasks, dependencies, configs chore: update xunit to 2.9.3
perf Performance improvement perf(spatial): optimize location query
build Build system or external dependencies build: add Aspire.Hosting.Redis package
ci CI/CD configuration ci: add migration verification step
style Code style (formatting, whitespace) style: apply dotnet format

The scope indicates which component or area is affected:

  • Component names: catalog, prism, identity, spatial, transport, bbu, alerts, workflow
  • Infrastructure: aspire, db, migrations, ci
  • Documentation: docs, adrs
  • Tooling: tools, cli, cortex
  • Cross-cutting: api, auth, logging

Subject Line Rules

  1. Imperative mood: "add feature" not "added feature" or "adds feature"
  2. No period at the end
  3. 50 characters or less (soft limit)
  4. Lowercase first letter (after type/scope prefix)
  5. Concise but descriptive: Enough context to understand without reading the diff

Body (When Needed)

Use the body for:

  • Explaining why the change was made (the subject explains what)
  • Describing how if the approach isn't obvious
  • Noting side effects or important details
  • Wrap at 72 characters

Linear Integration

Reference Linear issues in the footer for traceability:

feat(bbu): add camera processing stats view

Implements the analytics view for camera processing metrics
to support the operations dashboard.

Refs: SWE-123

For commits that complete an issue:

Closes: SWE-123

AI Co-Authorship

All AI-assisted commits MUST include co-authorship attribution:

feat(catalog): implement item expiration tracking

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

This:

  • Provides transparency about AI involvement
  • Enables analysis of AI contribution patterns
  • Maintains accountability and attribution standards

Breaking Changes

Document breaking changes in the footer:

refactor(identity): change token format to JWT

BREAKING CHANGE: Token format changed from opaque to JWT.
All clients must update their token parsing logic.

Examples

Good Commits

Simple fix:

fix(prism): handle null passport in lookup

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Feature with context:

feat(catalog): add bulk item status update endpoint

Allows updating status for multiple items in a single request,
improving performance for warehouse operations that need to
process hundreds of items.

Refs: SWE-456
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Documentation:

docs(adrs): add commit message guidelines ADR-053

Establishes conventions for commit messages including
conventional commits format, Linear integration, and
AI co-authorship attribution.

Closes: SWE-789
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Chore with details:

chore: update EF Core to 10.0.1

Addresses security advisory GHSA-xxxx-yyyy.
No breaking changes in this minor version.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Bad Commits (Avoid These)

Bad Why Better
fix bug No context fix(identity): prevent duplicate session creation
WIP Not atomic; don't commit incomplete work Finish the work or use a branch
Update stuff Meaningless refactor(spatial): rename location fields for clarity
Fixed the thing Daniel mentioned Internal context, not useful in history fix(transport): validate shipment dates before save
feat: Add new endpoint for getting items by type and also fix the sorting bug and update tests Too many changes in one commit Split into separate commits

Multi-Line vs Single-Line

Single-line (subject only):

  • Small, self-explanatory changes
  • The "what" is obvious from the diff
  • Examples: typo fixes, simple bug fixes, config changes

Multi-line (subject + body):

  • Changes that need explanation of "why"
  • Non-obvious implementation approaches
  • Changes with side effects or caveats
  • Features that benefit from context

Consequences

Positive

  1. Consistent History: All commits follow the same readable format
  2. Searchability: Easy to find commits by type (git log --grep="^feat")
  3. Automation Ready: Structured format enables changelog generation
  4. Clear Attribution: AI contributions are transparently documented
  5. Traceability: Linear references connect commits to their purpose
  6. Review Quality: Better context leads to better code reviews

Negative

  1. Learning Curve: Contributors must learn the format
  2. Overhead: Slightly more effort per commit
  3. Enforcement: Manual review required (no automated enforcement yet)

Mitigation Strategies

For Learning Curve:

  • Reference this ADR in CLAUDE.md
  • Include examples in developer onboarding
  • AI agents have this format built into their instructions

For Enforcement:

  • Consider git hooks for format validation (future)
  • Code review checklist includes commit message quality
  • AI agents should always generate compliant messages

Automation Potential

The structured format enables future tooling:

# Generate changelog from commits since last tag
git log v1.0.0..HEAD --oneline | grep "^feat\|^fix"

# Find all breaking changes
git log --grep="BREAKING CHANGE"

# Find commits related to an issue
git log --grep="SWE-123"

# Review AI contribution
git log --grep="Co-Authored-By: Claude"
  • ADR-035: Journal System (commit messages for audit trail changes)
  • Linear Issue Tracking: Integration pattern for issue references

References