| name | swpm-conventional-commits |
| id | swpm-conventional-commits |
| version | 1.0.0 |
| tags | ["swpm","conventional-commits","git","commit-messages"] |
| description | Conventional Commits 1.0.0 specification for SWPM. Defines commit message format with types (feat, fix, etc.), scopes, breaking changes, and body/footer conventions. Activates when writing commit messages or modifying git commits. |
SWPM Conventional Commits Standards
Use this skill when writing commit messages, questions about commit format, or when modifying git commits for SWPM.
When to Use
- User is writing a commit message - activates to ensure Conventional Commits 1.0.0 format
- Developer asks "What type should this commit be?"
- Questions about commit message structure
- Adding breaking changes to commits
- Do not use for CHANGELOG formatting (use
swpm-keepachangelog) or version numbering (use swpm-semver)
Conventional Commits 1.0.0 Rules
Commit Message Structure
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Types
Required type prefix:
- feat: A new feature (correlates with MINOR in SemVer)
- fix: A bug fix (correlates with PATCH in SemVer)
- BREAKING CHANGE: Introduces breaking API change (correlates with MAJOR in SemVer)
Additional Types (not mandated by spec, but allowed)
- build: Changes that affect build system or external dependencies
- chore: Other changes that don't modify src or test files
- ci: Changes to CI configuration files and scripts
- docs: Documentation only changes
- perf: A code change that improves performance
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do not affect the meaning of the code (white-space, formatting)
- test: Adding missing tests or correcting existing tests
Scope (Optional)
feat(parser): add ability to parse arrays
fix(api): resolve null pointer exception
Scope MUST be a noun describing a section of the codebase surrounded by parentheses.
Breaking Changes
Option 1: Using ! after type/scope
feat!: send an email to the customer when a product is shipped
feat(api)!: send an email to the customer when a product is shipped
Option 2: Using BREAKING CHANGE footer
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
Description
- MUST immediately follow the colon and space after type/scope
- Short summary of the code changes
- Use imperative mood: "add" not "added" or "adds"
Body (Optional)
- MUST begin one blank line after the description
- Free-form and MAY consist of any number of newline separated paragraphs
- Provide additional contextual information
Footers (Optional)
- MUST begin one blank line after the body
- Each footer MUST consist of a word token, followed by either
: or #
- Token MUST use
- instead of whitespace (e.g., Reviewed-by)
- Exception:
BREAKING CHANGE MAY be uppercase
SWPM Commit Conventions
Commit Message Examples
✅ Correct - Simple fix
fix: resolve volta version detection when not installed
✅ Correct - New feature with scope
feat(commands): add support for bun package manager
✅ Correct - Breaking change with !
feat!: remove deprecated `why` command
BREAKING CHANGE: The `why` command has been removed. Use `pnpm why` directly.
✅ Correct - With body and footers
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Reviewed-by: equiman
Refs: #123
✅ Correct - Build/CI changes
build: upgrade dependencies to latest versions
chore: update package.json scripts
ci: add Node.js 20 to build matrix
docs: update README with new command examples
test: add unit tests for args translator
refactor: simplify command translation logic
❌ Incorrect
fixed bug // Wrong type, not imperative
add new feature // Missing type prefix
Feat: new command // Wrong case (should be lowercase)
feat: add feature
extra line // Extra blank line in wrong place
Mapping to SemVer
Conventional Commits maps to Semantic Versioning:
- fix → PATCH (e.g.,
2.6.0 → 2.6.1)
- feat → MINOR (e.g.,
2.6.0 → 2.7.0)
- BREAKING CHANGE → MAJOR (e.g.,
2.6.0 → 3.0.0)
Commit Checklist
Before committing:
- Determine the correct type (feat, fix, etc.)
- Add scope if applicable:
feat(parser):
- Write imperative description after
:
- Add
! or BREAKING CHANGE: footer for breaking changes
- Add body with blank line separation if needed
- Add footers (Reviewed-by, Refs, etc.) if needed
- Ensure description uses imperative mood
Example Questions
Q: "What type should I use for updating dependencies?"
A: Use build: or chore::
build: upgrade dependencies to latest versions
Q: "How do I indicate a breaking change?"
A: Use ! after type or add BREAKING CHANGE: footer:
feat!: remove deprecated command
BREAKING CHANGE: Command removed in this version.
Q: "What's the difference between feat and fix?"
A: feat adds new functionality (→ MINOR version), fix patches bugs (→ PATCH version).
Q: "Can I use multiple types in one commit?"
A: No, each commit should have one type. Make separate commits for different changes.
Q: "Should I use uppercase FEAT or lowercase feat?"
A: Use lowercase feat:, but BREAKING CHANGE: footer MUST be uppercase.
Observations
Before helping with commit messages:
- Check if the change is a new feature (feat), bug fix (fix), or breaking change (BREAKING CHANGE)
- Determine if a scope applies (e.g.,
commands, args, docs)
- Verify description uses imperative mood ("add" not "added")
- Check if commit includes body/footers
- Reference: https://www.conventionalcommits.org/en/v1.0.0/
Reference
Full Conventional Commits specification: https://www.conventionalcommits.org/en/v1.0.0/
