Commit

Commit Skill for OpenZeppelin UI Monorepo

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

Critical Requirements

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

Commit Format

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

[optional body]

[optional footer(s)]

Rules

Commit Types

Allowed Scopes

The commitlint config enforces these scopes:

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:

1. Formatting check: Runs pnpm format:check
2. Commit message validation: Runs commitlint

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

Pre-push Hooks

Before pushing, these checks run:

1. Formatting and linting: Runs pnpm fix-all
2. Type checking: Runs pnpm typecheck
3. 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