commit-standards

Commit Standards

Create consistent, well-documented commits that maintain a clear project history and changelog.

When This Skill Applies

CRITICAL: Every filesystem change should be committed before continuing to prevent data loss, especially during iterative sessions.

• User explicitly asks to commit (e.g., "commit this", "let's commit", "/commit")
• After any filesystem change - files created, modified, or deleted
• After completing an SDD workflow that produces artifacts:
• After /sdd I want to initialize a new project creates specs/plans
• After /sdd I want to create a new feature creates a change workflow
• After /sdd I want to approve the spec creates a PLAN.md
• After /sdd I want to start implementing completes phases
• After /sdd I want to verify the implementation completes a change
• Before starting a new task or switching context

Commit Message Format

[Action] [Component]: [Description], bump to [project version]

[Detailed explanation - same as changelog body]

Co-Authored-By: SDD Plugin vX.Y.Z

IMPORTANT: Always verify the project version with the user (appears in commit message and changelog).

Actions

| Action | Use When | |--------|----------| | Add | New feature or file | | Fix | Bug fix | | Update | Enhancement to existing feature | | Remove | Deletion | | Refactor | Code restructuring without behavior change | | Docs | Documentation only | | Tasks | Task management changes |

Examples

Add user-auth: Implement login and registration flow, bump to 1.2.0

- Token-based authentication with refresh tokens
- Registration with email verification
- Password reset flow
- Session management utilities

Co-Authored-By: SDD Plugin v5.1.0

Fix api-gateway: Resolve timeout on large payloads, bump to 1.1.1

Increased default timeout from 30s to 120s for file upload endpoints.
Added chunked transfer encoding support.

Co-Authored-By: SDD Plugin v5.1.0

Docs specs: Add user-auth change spec and plan

Created change spec and implementation plan for user authentication feature.

Co-Authored-By: SDD Plugin v5.1.0

Note: The "bump to X.Y.Z" suffix is only included when a version bump occurs.

Changelog Standards

Directory Structure

changelog/
├── v1.md    # All 1.x releases
├── v2.md    # All 2.x releases
├── v3.md    # All 3.x releases
└── ...

All changelog entries go in the appropriate changelog/vN.md file based on major version.

Entry Format

## [x.y.z] - YYYY-MM-DD

### [Category]

- **[component]**: Description of change
  - Detail 1
  - Detail 2

### Rationale

Why this change was made (for significant changes).

Categories

| Category | Use When | |----------|----------| | Added | New features | | Changed | Changes to existing functionality | | Enhanced | Improvements to existing features | | Fixed | Bug fixes | | Removed | Removed features |

Single File Update

Add the changelog entry to changelog/vN.md (where N is the major version).

Example: Version 5.1.0 → add entry to changelog/v5.md

Commit Body = Changelog Body

The detailed description in the commit message should be identical to the changelog entry body. Write once, use for both:

# Commit message body:
- Token-based authentication with refresh tokens
- Registration with email verification
- Password reset flow

# Changelog entry body (same content):
- **[user-auth]**: Implement login and registration flow
  - Token-based authentication with refresh tokens
  - Registration with email verification
  - Password reset flow

Version Bump Guidelines

Project Version Location

The project version is stored in sdd/sdd-settings.yaml. Delegate to the project-settings skill for the version location and format — it returns the version field from the project settings root, following semver (MAJOR.MINOR.PATCH).

Semver

| Type | Version Change | Use When | |------|----------------|----------| | PATCH | x.x.Z | Bug fixes, small improvements | | MINOR | x.Y.0 | New features, backwards compatible | | MAJOR | X.0.0 | Breaking changes |

When to Bump

Version bump is required when changing:

• Source code in src/ or component directories
• Public API or contracts
• Configuration that affects behavior

Version bump is NOT required for:

• Documentation-only changes
• Test-only changes
• Development tooling changes
• Spec/plan creation (planning phase)

SDD-Aware Practices

Reference Change Directories

When implementing from a spec, reference the change directory:

Add user-auth: Implement login flow (changes/2026/01/user-auth)

Implements phase 1 of the user-auth change spec.

Commit at Key Points

1. After spec/plan creation - Preserve planning work before implementation
2. After each implementation phase - Capture incremental progress
3. After completing all phases - Mark the change as complete

Update Plan Status

When a commit completes work tracked in a plan, update the plan status:

## Status: COMPLETED

**Completed: 2026-01-29**

Best Practices

One Commit = One Changelog Entry

If your changes would result in multiple changelog entries, split them into separate commits.

Wrong:

git add . && git commit -m "Add feature A, fix bug B, refactor C"
# Results in 3 changelog entries in one commit

Correct:

git add feature-files && git commit -m "Add feature A"
git add bugfix-files && git commit -m "Fix bug B"
git add refactor-files && git commit -m "Refactor C"

Atomic Commits

Each commit should represent one logical change. If you can't describe the commit in one sentence, it's probably too big.

Message Style

• Imperative mood: "Add feature" not "Added feature"
• Subject under 72 characters
• Body explains "why" not just "what"

Never Amend Pushed Commits

Before amending, check if the commit has been pushed:

git log origin/main..HEAD --oneline

• If the commit appears → Safe to amend
• If NOT → Create a new commit instead

Verification Checklist

Before committing, verify:

[ ] Version in sdd/sdd-settings.yaml updated (if version bump needed)
[ ] Changelog entry in changelog/vN.md
[ ] Commit body matches changelog body
[ ] All related files staged
[ ] Commit message follows format
[ ] Co-Authored-By includes SDD Plugin version

Quick Reference

Any filesystem change? → Commit immediately to prevent data loss

Code change? → Version bump → Changelog (changelog/vN.md) → Commit
Docs only?   → Changelog (changelog/vN.md) → Commit
Spec/plan?   → Changelog (changelog/vN.md) → Commit

Always: Verify project version with user before committing

Input / Output

This skill defines no input parameters or structured output.