Ref-002: Commit Message Standards

Type

Reference Documentation

Traceability

Purpose

Defines the canonical commit message structure, conventions, and traceability requirements for the SEA-Forge™ platform to ensure clarity, automation support, and audit compliance.

Core Principles

  1. Clarity & Actionability: Every commit message must convey what changed and why at a glance
  2. Blend of Code & Reasoning: Surface rationale for architectural, non-obvious, or risky changes; keep routine commits concise
  3. Traceability & Automation: Reference relevant spec IDs (PRD-xxx, ADR-xxx, SDS-xxx, TS-xxx, DEV-, AI_) to support automated workflows
  4. Cognitive Ergonomics: Use a small, meaningful emoji set to improve scanability—never for decoration
  5. Validation & Risk Awareness: Explicitly note testing, risks introduced, and mitigation strategies

Commit Message Structure

Required Elements

Section Requirements
Subject ≤ 72 characters, imperative mood (“Add”, “Fix”, “Refactor”), summarizes main action
Body Wrapped at 72-100 columns, explains what changed and why (not just how)
Traceability References spec/issue IDs (e.g., PRD-xxx, ADR-xxx, SDS-xxx, TS-xxx, DEV-, AI_)
Emojis Small documented set for scanning (✨, 🐛, ♻️, ⚠️) - no decorative use
Risks Calls out security, performance, UX, or operational risks and mitigation
Validation Notes updated tests, docs, or scripts; mentions deferred follow-ups

Analytical Context Guidelines

DO include reasoning for:

Keep concise for:

Canonical Emoji Vocabulary

Emoji Type Usage
✨ feat New features or enhancements
🐛 fix Bug fixes
♻️ refactor Code restructuring without functional changes
⚠️ breaking Breaking changes or critical warnings

Examples

Feature with Traceability

1
2
3
4
5
6

✨ feat(auth): add two-factor authentication

Implements TOTP-based 2FA to enhance account security.
Motivation: Addresses PRD-102 and mitigates risk of credential stuffing attacks.
Tested with new integration tests; docs updated.
Refs: PRD-102, SDS-45

Bug Fix with Root Cause

1
2
3
4
5
6

🐛 fix(ui): resolve dropdown misalignment on profile page

Dropdown was misaligned due to conflicting CSS.
Root cause: Overlapping flexbox rules.
Tested on all supported browsers.
Fixes: DEV-789

Refactor with Rationale

1
2
3
4
5
6

♻️ refactor(user-service): modularize user validation logic

Split monolithic validateUser() into smaller, testable functions.
Motivation: Improves maintainability and test coverage.
Unit tests added.
Refs: ADR-112

Breaking Change with Risk & Mitigation

1
2
3
4
5
6

⚠️ feat(config): support config inheritance via 'extends' key

BREAKING CHANGE: Config files now support 'extends' for modularity.
Migration: Existing configs must add 'extends' or update structure.
Mitigation: Migration script provided; see docs.
Refs: ADR-102, PRD-45

Automation Integration

This standard is enforced via Copilot guardrails defined in .github/instructions/commit-msg.instructions.md.

Compliance Requirements

All commits MUST:

  1. Use imperative mood in subject line
  2. Include traceability references for non-trivial changes
  3. Document risks and validation for significant changes
  4. Use approved emoji vocabulary only