Skip to content

Conventional Commits and Commitizen

Use structured commit messages so the release workflow can identify fixes, features, and breaking changes. Commitizen provides an interactive prompt through the project's existing yarn commit command.

This guide covers committing and pushing extension changes to your own project repository. Follow Versioning and Releases when your project is ready for a release.

1. Review and stage your changes

From your project repository, check the changed files, then stage your changes:

git status
git add .

Keep custom forms and configuration inside src/extensions/. Do not include .env, credentials, node_modules, dist, or temporary files generated while creating a local installation package.

2. Open the Commitizen prompt

Install project dependencies with yarn install if you have not already done so, then run:

yarn commit

The commit script runs git-cz with the cz-conventional-changelog adapter already configured in package.json.

3. Complete the prompts

For a routine bug fix, follow this flow:

Prompt What to enter
Commit type fix for a bug fix. Choose the type that describes the actual change.
Scope Leave blank and press Enter.
Short description A clear English description, such as correct the monthly total label. Keep it within 95 characters and the limit shown by the prompt.
Long description Leave blank for a simple change, or explain context that helps reviewers.
Breaking changes Answer No for a compatible change. If an existing integration must change, discuss it with the maintainer and describe the breaking change accurately.
Open issues Answer No when no issue reference is needed. Use the project's agreed issue reference when applicable.

For a new capability, use feat rather than labelling it as a fix. Use your project’s review process when the type or compatibility impact is unclear.

A simple resulting message looks like:

fix: correct the monthly total label

4. Understand the versioning effect

The release configuration uses the Conventional Commits preset. With the standard analyzer rules used by the project:

Commit Meaning Next release, starting from 1.2.3
fix: correct the monthly total label Compatible bug fix Patch: 1.2.4
feat: add a client follow-up form Compatible new feature Minor: 1.3.0
perf: reduce metadata lookup time Performance improvement Patch: 1.2.4
A commit with a BREAKING CHANGE: footer Change requiring existing consumers to adapt Major: 2.0.0
docs: clarify the form setup or chore: update development notes Documentation or maintenance without another release-triggering change No release by itself

These conventions distinguish compatible fixes, new features, and breaking changes. See the Conventional Commits specification.

The analyzer evaluates commits since the previous matching release tag and chooses the highest applicable release type. A first release uses the release tool's initial version policy; it does not simply increment the version displayed in package.json. See the commit analyzer rules.

Commitizen formats the message; it does not publish a release. Keep meaningful commit messages in the history that reaches main, because those are the messages the release analyzer reads.

5. Push to your project repository

Push the commit to your project's own repository:

git push

Open your project repository on GitHub and check that the commit appears.

Next step

Use Create a Local Installation ZIP for testing, or Versioning and Releases for a published installation package.