Git Conventions

Development

git-conventions

Git Conventions is an Agent Skill for development published in the strapi/strapi repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when writing any git commit message, PR title, or squash subject in the Strapi repo. Trigger whenever a commit/PR subject is being drafted, even if the user didn't say the word "commit".

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/strapi/strapi/blob/HEAD/.ai/skills/git-conventions/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/git-conventions, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Strapi Commit Conventions

Source of truth: CONTRIBUTING.md ("Git Conventions") and .commitlintrc.ts.

Format

type[(scope)]: subject

body

Type and subject are lowercase
No period at end of subject
Subject is descriptive — say what the commit is about, not how the code achieves it (see Subject Rules below)
Scope is recommended (not enforced by commitlint): prefer including a package or feature area so the change is easy to place and to filter in changelogs — e.g. fix(core/core): ..., feat(content-manager): ..., chore(deps): .... Use a real package or feature name (admin, content-manager, database, graphql, upload, i18n, deps, commitlint)
Body line length is not enforced (the body-max-line-length rule is disabled)
Merge commits like Merge branch '<x>' into <y> are ignored by commitlint

Allowed Types

The full enforced list comes from .commitlintrc.ts:

Type	Use for
`feat`	A new feature
`fix`	A bug fix
`enhancement`	Improvement to an existing feature (perf, refactor, UX polish)
`chore`	Internal cleanup, tooling, refactor with no behavior change, dep bumps
`docs`	Documentation only
`test`	Adding or updating tests
`ci`	CI/CD pipeline changes
`security`	Security fixes or hardening (often `security(deps): ...`)
`revert`	Reverting a previous commit
`release`	Release commits (reserved for release tooling)
`future`	Work behind a future flag

Types not in the list (and therefore rejected by commitlint): perf, refactor, style, build, improvement, wip.

Note: refactor and perf are rejected as type prefixes, but the underlying work is still valid — route it through enhancement (when it improves the product/feature) or chore (when it's internal housekeeping with no product change). See the Decision Guide below.

Subject Rules (from CONTRIBUTING.md)

The subject summarises what the commit is about, not how the code achieves it.

Prefer a scope: type(scope): subject (e.g. fix(core/core): xxx). The scope points at the package or feature area touched and keeps the history easy to filter.

feat(scope): <what the feature is>
fix(scope): <what the problem is> — describe the bug, not the fix
chore(scope): <what the PR is about>
docs(scope): <what is documented>

⚠️ For fix commits, the subject must describe the bug being fixed, not the solution. e.g. fix: unable to publish documents due to missing permissions — not fix: add permission check.

Decision Guide

New user-facing capability? → feat
Existing feature is broken? → fix (describe the bug)
Existing feature, code, UX, or perf gets meaningfully better (including internal swaps that improve operational behaviour)? → enhancement
Repo housekeeping with no product change — deps, tooling, build config, examples cleanup, lint/format-only changes? → chore (use chore(deps): ... for dep bumps)
Documentation only? → docs
Tests only? → test
CI/workflow files only? → ci
Security advisory or hardening? → security
Behind a future flag? → future