---
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:

1. Determine the correct type (feat, fix, etc.)
2. Add scope if applicable: `feat(parser):`
3. Write imperative description after `: `
4. Add `!` or `BREAKING CHANGE:` footer for breaking changes
5. Add body with blank line separation if needed
6. Add footers (Reviewed-by, Refs, etc.) if needed
7. 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/