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
1---2name: git-conventions3description: 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".4metadata:5 source: https://skillmd.com/skills/strapi/git-conventions6---78# Strapi Commit Conventions910Source of truth: [CONTRIBUTING.md](../../../CONTRIBUTING.md) ("Git Conventions") and [.commitlintrc.ts](../../../.commitlintrc.ts).1112## Format1314```15type[(scope)]: subject1617body18```1920- Type and subject are **lowercase**21- No period at end of subject22- Subject is descriptive — say **what** the commit is about, not **how** the code achieves it (see Subject Rules below)23- 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`)24- Body line length is **not** enforced (the `body-max-line-length` rule is disabled)25- Merge commits like `Merge branch '<x>' into <y>` are ignored by commitlint2627## Allowed Types2829The full enforced list comes from [.commitlintrc.ts](../../../.commitlintrc.ts):3031| Type | Use for |32| ------------- | ---------------------------------------------------------------------- |33| `feat` | A new feature |34| `fix` | A bug fix |35| `enhancement` | Improvement to an existing feature (perf, refactor, UX polish) |36| `chore` | Internal cleanup, tooling, refactor with no behavior change, dep bumps |37| `docs` | Documentation only |38| `test` | Adding or updating tests |39| `ci` | CI/CD pipeline changes |40| `security` | Security fixes or hardening (often `security(deps): ...`) |41| `revert` | Reverting a previous commit |42| `release` | Release commits (reserved for release tooling) |43| `future` | Work behind a future flag |4445Types **not** in the list (and therefore rejected by commitlint): `perf`, `refactor`, `style`, `build`, `improvement`, `wip`.4647> 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.4849## Subject Rules (from CONTRIBUTING.md)5051The subject summarises **what** the commit is about, not **how** the code achieves it.5253Prefer 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.5455- `feat(scope): <what the feature is>`56- `fix(scope): <what the problem is>` — describe the bug, not the fix57- `chore(scope): <what the PR is about>`58- `docs(scope): <what is documented>`5960> ⚠️ 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`.6162## Decision Guide6364- New user-facing capability? → `feat`65- Existing feature is broken? → `fix` (describe the bug)66- Existing feature, code, UX, or perf gets meaningfully better (including internal swaps that improve operational behaviour)? → `enhancement`67- Repo housekeeping with no product change — deps, tooling, build config, examples cleanup, lint/format-only changes? → `chore` (use `chore(deps): ...` for dep bumps)68- Documentation only? → `docs`69- Tests only? → `test`70- CI/workflow files only? → `ci`71- Security advisory or hardening? → `security`72- Behind a future flag? → `future`