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.