Name: Commit
Author: OpenZeppelin

name	commit
description	Creates commits following the monorepo's Conventional Commits standard with proper GPG signing, scope selection, and pre-commit validation. Reminds about changesets for package changes. Use when creating commits, writing commit messages, or when the user asks to commit changes.

Commit Skill for OpenZeppelin UI Monorepo

This skill guides committing changes following the project's Conventional Commits standard.

Critical Requirements

Never commit directly to main - Always check the current branch before committing. If on main, create a new branch first (see Commit Workflow below).
Always run commits outside sandbox - Full shell permissions required for GPG signing and pre-commit hooks
Never use --no-gpg-sign - All commits must be GPG-signed
Never use --no-verify - Pre-commit hooks must run

Commit Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Rules

Rule	Requirement
Header max length	100 characters
Subject case	lowercase (never sentence-case, start-case, pascal-case, upper-case)
Subject ending	No period
Scope	Required (scope-empty is enforced)
Body line length	Max 100 characters
Body leading blank	Required if body present

Commit Types

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Formatting, whitespace (no code change)
`refactor`	Code change that neither fixes a bug nor adds a feature
`perf`	Performance improvement
`test`	Adding or correcting tests
`build`	Build system or external dependencies
`ci`	CI configuration changes
`chore`	Other changes (not src or test)
`revert`	Reverts a previous commit
`wip`	Work in progress (avoid if possible)

Allowed Scopes

The commitlint config enforces these scopes:

Scope	Description
`types`	Type definitions package
`utils`	Utility functions package
`styles`	Styles package
`components`	Components package
`renderer`	Renderer package
`react`	React integration package
`storage`	Storage package
`deps`	Dependencies
`config`	Configuration files
`ci`	CI/CD configuration
`docs`	Documentation
`tests`	Test-related changes
`release`	Release automation
`examples`	Example applications
`common`	Common/shared code
`spec`	Specification documents

Commit Workflow

# 1. Stage changes
git add <files>

# 2. Commit with HEREDOC (recommended for multi-line messages)
git commit -m "$(cat <<'EOF'
feat(components): add new contract widget

Implements a reusable widget component for displaying
contract state with real-time updates.
EOF
)"

Changeset Reminder

Before committing changes to packages/ directory, check if a changeset is needed.

A changeset is required when:

Adding features to published packages
Fixing bugs in published packages
Making breaking changes

Check for existing changesets:

ls .changeset/*.md

If no changeset exists for your changes, create one:

pnpm changeset

Published packages in this monorepo:

@openzeppelin/ui-types
@openzeppelin/ui-utils
@openzeppelin/ui-styles
@openzeppelin/ui-components
@openzeppelin/ui-renderer
@openzeppelin/ui-react
@openzeppelin/ui-storage

Pre-commit Hooks

The following checks run automatically on commit:

Formatting check: Runs pnpm format:check
Commit message validation: Runs commitlint

If pre-commit fails, fix the issues and commit again.

Pre-push Hooks

Before pushing, these checks run:

Formatting and linting: Runs pnpm fix-all
Type checking: Runs pnpm typecheck
Tests: Runs pnpm test

If pre-push fails, fix the issues and push again.

Breaking Changes

Indicate breaking changes with ! after type/scope:

feat(types)!: change network config interface

Or with a footer:

feat(types): change network config interface

BREAKING CHANGE: NetworkConfig interface now requires chainId property.
All consumers must update their configuration.

Common Pitfalls

Sandbox Mode Errors

Symptom: Commit fails with permission errors, GPG signing fails, or hooks don't run.

Fix: Run commit commands with full shell permissions (outside sandbox).

Invalid Scope

Symptom: scope-enum error from commitlint.

Fix: Use one of the allowed scopes above. If a new scope is justified, update commitlint.config.js.

Subject Case Error

Symptom: subject-case error.

Fix: Use lowercase for the entire subject:

Bad: Add new feature
Good: add new feature

Missing Scope

Symptom: scope-empty error from commitlint.

Fix: Always include a scope. Choose the most relevant package or category.

Examples

# Feature with package scope
feat(components): add network badge component

# Fix with package scope
fix(utils): correct address validation for checksums

# Refactor with package scope
refactor(renderer): simplify form field rendering logic

# Specification documents
docs(spec): add data model for extend example apps feature

# Documentation
docs(examples): add wallet connection tutorial

# Test changes
test(react): add unit tests for useWalletComponents hook

# Dependencies update
chore(deps): update vitest to v3.2.4

# CI changes
ci(config): add coverage threshold checks

# Release automation (auto-generated, usually ignored by commitlint)
chore(release): version packages

Quick Reference

# Stage and commit
git add . && git commit -m "feat(components): add feature"

# Check commit format is valid
echo "feat(components): add feature" | npx commitlint

# View recent commit formats for reference
git log --oneline -10

# Amend last commit (only if not pushed!)
git commit --amend

# Create changeset for package changes
pnpm changeset

name	commit
description	Creates commits following the monorepo's Conventional Commits standard with proper GPG signing, scope selection, and pre-commit validation. Reminds about changesets for package changes. Use when creating commits, writing commit messages, or when the user asks to commit changes.