10up-commit-messages

name	10up-commit-messages
description	Write clear, consistent commit messages following 10up conventions. Uses conventional commit style with lowercase formatting. Use when creating commits, writing PR descriptions, or generating changelogs.
license	MIT
compatibility	Works with any git-based project. Integrates with changesets for versioning.
alwaysApply	true
metadata	{"author":"10up","version":"1.0"}

10up Commit Messages

This skill guides you through writing clear, consistent commit messages that follow 10up conventions and conventional commit standards.

When to Use

• Creating git commits
• Writing commit messages for the user
• Generating PR descriptions
• Documenting changes in changelogs
• Reviewing commit message quality

Format

<type>: <description>

[optional body]

[optional footer]

Commit Types

Type	When to Use	Example
fix:	Bug fixes and error corrections	fix: resolve block validation error on save
feature:	New features or functionality	feature: add hero section block with background image support
chore:	Maintenance, dependencies, build changes	chore: update 10up-toolkit to v6.5.0
documentation:	Documentation only changes	documentation: add InnerBlocks usage examples to README
refactor:	Code changes without functional impact	refactor: extract media upload logic to custom hook
test:	Adding or updating tests	test: add unit tests for block registration
style:	Formatting, whitespace (not CSS)	style: apply prettier formatting to block files
performance:	Performance improvements	performance: lazy load carousel images below fold

Rules

1. Use lowercase throughout

# Good
fix: ensure carousel icon settings fall back to defaults correctly

# Bad - capitalized
Fix: Ensure carousel icon settings fall back to defaults correctly

2. Keep subject under 72 characters

Short, scannable subjects are easier to read in git log.

# Good (58 chars)
feature: add responsive breakpoint controls to grid block

# Bad (93 chars)
feature: add responsive breakpoint controls to the grid block component for better mobile support

3. Use imperative mood

Write as if giving a command: "add", "fix", "update" — not "added", "fixed", "updated".

# Good - imperative
fix: resolve attribute type mismatch in hero block
feature: add toggle for showing post excerpt

# Bad - past tense
fix: resolved attribute type mismatch in hero block
feature: added toggle for showing post excerpt

4. No period at the end

# Good
documentation: update contributing guidelines

# Bad
documentation: update contributing guidelines.

5. Be specific but concise

The subject should explain WHAT changed. Use the body for WHY if needed.

# Good - specific
fix: prevent duplicate block registration on hot reload

# Bad - vague
fix: block issue
fix: stuff

Examples

Simple commits

fix: ensure carousel icon settings fall back to defaults correctly
feature: add timeline block support
chore: apply changesets
fix: remove beta label from navigation plugin
refactor: simplify release process
documentation: update contributing guidelines
test: add cypress tests for accordion interactions
performance: reduce bundle size by tree-shaking unused icons

Commit with body

For complex changes, add a body explaining the context:

fix: prevent block validation errors after attribute changes

The hero block was showing "Invalid block" after we renamed
the 'title' attribute to 'heading'. Added a deprecation entry
with proper migration to handle existing content.

Fixes #123

Commit with scope (optional)

For monorepos or large projects, you can add a scope:

fix(accordion): ensure content panel respects max-height
feature(theme): add dark mode style variation
chore(deps): update @wordpress/scripts to 27.0.0

Breaking changes

Use ! after type or add BREAKING CHANGE: footer:

feature!: change block API to use render.php instead of save.js

BREAKING CHANGE: All blocks must now use dynamic rendering.
Static save functions are no longer supported.

Avoid These Patterns

# Missing type prefix
fixed the carousel bug

# Too vague
fix
update
changes

# Capitalized with period
Fix: Ensure carousel works.

# Past tense
Added new feature

# Too long
feature: add responsive breakpoint controls to the grid block component for better mobile support and tablet compatibility

# Describing files instead of changes
fix: update index.js

Multi-file Commits

When a commit touches multiple files, describe the overall change:

# Good - describes the change
feature: add image lazy loading to all media blocks

# Bad - lists files
feature: update hero.php, gallery.php, and image.php

Automated Commits

Some commits are generated automatically by CI/CD:

• chore: apply changesets — Generated when changesets are versioned
• chore: release v1.2.3 — Generated by release automation
• Merge commits follow git's default format

Working with Changesets

For projects using changesets (common in 10up monorepos):

1. Don't duplicate info — The changeset file describes the change for the changelog
2. Commit message = what — Brief description of the code change
3. Changeset = why + impact — User-facing description for release notes

# Create changeset
npx changeset

# Commit with simple message
git commit -m "feature: add lazy loading to media blocks"

PR Titles

PR titles should follow the same format as commit messages:

fix: resolve block validation error after attribute rename
feature: add hero section block with parallax support

For squash-merge workflows, the PR title becomes the commit message.

Verification

When reviewing commits:

1. Type matches the change (fix vs feature vs chore)
2. Subject is lowercase
3. Under 72 characters
4. Imperative mood
5. No trailing period
6. Specific enough to understand without reading diff

Procedure

When asked to create a commit:

1. Identify the type of change (fix, feature, chore, etc.)
2. Write a concise subject in imperative mood
3. Keep it under 72 characters
4. Use lowercase throughout
5. Add body only if context is needed
6. Include footer for breaking changes or issue references