How We Branch and Commit
Branch naming
Every branch is named the same way, so anyone can tell what it's for at a glance:
feat/123-signup-page
It has three parts:
- What kind of work it is — a short prefix (see the table).
- The issue or ticket number — the issue this work tracks (here,
123). - A short description — a few lowercase words joined by dashes. Keep it brief.
Pick the prefix that matches your work:
| Prefix | Use it for |
|---|---|
feat/ | A new feature or improvement |
fix/ | Fixing a bug someone reported |
hotfix/ | An urgent fix that can't wait for the normal flow |
chore/ | Work that isn't app code — dependencies, config, docs |
experiment/ | A quick experiment you don't plan to merge |
Commit messages
A commit message starts with a short label for the kind of change, then a plain description:
feat(signin): add login screens
In that example, feat is the kind of change, (signin) is the area it touches (optional), and the rest describes what you did. Most of your commits will use one of these labels:
feat— a new featurefix— a bug fixdocs— documentation onlychore— maintenance that doesn't change how the app behavesrefactor— reworking code without changing what it doestest— adding or updating tests
If one line isn't enough, leave a blank line and add more detail underneath.
Details
| Label | For |
|---|---|
feat | A new feature |
fix | A bug fix |
chore | Routine maintenance that doesn't change source code |
docs | Documentation-only changes |
style | Formatting that doesn't change meaning (whitespace, etc.) |
refactor | Reworking code without changing what it does |
test | Adding or changing tests |
perf | A change that improves performance |
build | Changes to the build system or dependencies |
ci | Changes to CI/CD |
revert | Reverting an earlier change |
config / setup | Changes to configuration or setup steps |
security | Security improvements |
localize | Translation / language changes |
wip | Work in progress — part of unfinished work |
This style is called Conventional Commits, if you'd like to read more about it.
Breaking changes
If your change breaks something other code relies on, add a ! after the label and explain it at the bottom of the message:
feat(api)!: change the users list endpoint url
BREAKING CHANGE: the old '/api/v1/users' endpoint no longer works.
What's checked for you, and what isn't
Some of this is automatic; the rest is on you.
- Formatting and linting are checked. Some repos tidy formatting when you commit, and every PR has to pass
npm run formatandnpm run check-lint(ormvn spring-javaformat:applyfor Java). A PR that fails these won't be merged. - The commit message isn't checked by any tool — nothing will catch a wrong label automatically. So follow the format yourself; reviewers look for it.
Main branches and flow
Open question — the source/destination branch strategy (which long-lived branches exist, and where feature branches merge) isn't written down: the core repo's CONTRIBUTING.md leaves its "Main Branches" and "Gitflow" sections as empty placeholders. Document the actual flow here before publishing rather than assuming a standard gitflow.