Conventional Commits — Team Guidelines with Lots of Examples

-

 

The format (one line)

type(scope)!: subject
  • type: one of feat, fix, perf, refactor, chore, docs, test, build, ci, style, revert
  • scope (optional): focus area like frontend, backend, api, db, billing, search, auth, infra
  • !: indicates a breaking change (also add a BREAKING CHANGE: footer in the body)

Rules we enforce (team policy)

  • Header
    • Max 100 characters
    • No trailing period
  • Body (optional but recommended)
    • Leave one blank line between header and body
    • Explain what and why; wrap lines around ~72–100 chars
  • Breaking changes
    • Either: feat(scope)!: ...
    • Or add a footer line:
      BREAKING CHANGE: describe impact and migration

SemVer mapping (cheat-sheet)

  • fix: → PATCH
  • feat: → MINOR
  • BREAKING CHANGE or ! → MAJOR

Copy-paste templates

Simple one-liner

type(scope): short imperative summary

With body, references, and breaking footer

type(scope)!: short imperative summary

Longer body explaining what changed and why. Include context and alternatives
considered if helpful.

BREAKING CHANGE: describe the impact and how to migrate.
Refs: #123, #124

Revert

revert: type(scope): original summary

This reverts commit <sha>.

Quick examples (expanded)

Features

  • feat(frontend): add dropzone upload with progress
  • feat(api): support cursor-based pagination
  • feat(auth): refresh-token rotation with inactivity timeout
  • feat(search): enable fuzzy matching with trigram index
  • feat(billing): add SEPA Direct Debit
  • feat(notifications): email templates with MJML
  • feat(settings): dark mode toggle and persistence
  • feat(reports): export to CSV and XLSX
  • feat(files): resumable uploads with chunk retry

Fixes

  • fix(backend): parse CSV with semicolon delimiter
  • fix(api): return 400 for invalid cursor
  • fix(auth): handle expired refresh token gracefully
  • fix(db): correct uuid default in migration
  • fix(frontend): guard against undefined organization
  • fix(logging): redact secrets from error payloads
  • fix(cli): ensure --help exits with code 0
  • fix(i18n): escape placeholders in translation strings

Performance

  • perf(db): batch inserts using COPY
  • perf(cache): pipeline Redis writes to reduce RTT
  • perf(api): reuse HTTP client to cut TLS handshakes
  • perf(images): lazy-load thumbnails on listing page

Refactors

  • refactor(api): extract pagination utils
  • refactor(auth): isolate token validation middleware
  • refactor(db): rename column quantities -> items_json
  • refactor(ui): co-locate hooks with feature modules
  • refactor(router): flatten nested controllers

Documentation

  • docs: update README with versioning instructions
  • docs(contributing): add commit message guide
  • docs(api): examples for /licenses endpoints
  • docs(runbook): add on-call escalation steps

Tests

  • test: add unit tests for version endpoint
  • test(e2e): onboarding happy-path scenario
  • test(api): contract tests for /auth/token
  • test(fixtures): generate sample invoices

Build / CI / Chore / Style

  • build(docker): switch to multi-stage build
  • build(makefile): add target db.reset
  • build(nix): pin flake inputs for reproducible builds
  • ci(github): cache pnpm installs
  • ci(pipeline): run migrations before smoke tests
  • chore(deps): bump fastapi from 0.111 to 0.115
  • chore(release): 2.0.0
  • style(css): normalize heading sizes and spacing
  • style: apply Prettier/Black formatting
  • chore(lint): enable import order checks

Reverts & Breaking changes

  • revert: feat(api): support cursor-based pagination
  • feat!: drop Node 16 support
  • refactor(api)!: remove deprecated v1 upload endpoints

Example breaking footer

feat(auth)!: enforce PKCE for public clients

BREAKING CHANGE: public clients must use PKCE. Add code_challenge and
code_verifier to the authorization code flow to migrate.

Detailed bug fix

fix(db): prevent transaction deadlock on concurrent updates

Use SELECT ... FOR UPDATE SKIP LOCKED to avoid blocking high-traffic updates
on the same organization row. This reduces average latency by ~35% under load.

Scopes: how to pick good ones

Use stable, short labels that match product areas or subsystems:

  • Subsystems: api, frontend, backend, db, auth, telemetry
  • Feature areas: upload, billing, org, search, alerts, reports
  • Tooling/infra: docker, nix, github, pipeline, helm, infra

Avoid one-off misc scopes; favor consistent names across repos.

Git tips (handy oneliners)

Commit with a body

git commit -m "feat(api): support cursor-based pagination"            -m "Adds stable cursor encode/decode and validates limit."            -m "Refs: #123"

Amend the last commit message

git commit --amend

Revert a commit

git revert <sha>

Recommended tooling

  • Linting: @commitlint/cli + @commitlint/config-conventional
  • Hooks: Husky or native Git hooks to enforce on commit/push
  • Releases: semantic-release (or similar) to tag & generate changelogs


Comments

Post a Comment

Popular posts from this blog

Mount StorageBox to the server for backup

-
  Quickly  solution Install cifs-utils: apt-get install cifs-utils Adjust and add the following lines to   crontab -e   : # reboot # This one should be moved to /etc/fstab @reboot /sbin/mount.cifs -o user=uXXXXXXXX,pass=xxxxxXXXXXX//uXXXXXX.your-storagebox.be/backup /mnt/storagebox_jobsites_backup/ SAMBA/CIFS You can mount your Storage Box via Samba/CIFS. You can use the following UNC path. If you are using your main account, the share name is  backup . If you are using a sub-account, you must use the username of the sub-account as the username and share name. Linux/Unix: //<username>.your-storagebox.de/<share_name> Windows \\<username>.your-storagebox.de\<share_name> If you use a FritzBox Router from AVM, you need to deactivate the NetBIOS filter for Samba/CIFS to work. Please check the AVM knowledge base for more information.  https://en.avm.de/service/knowledge-base/dok/FRITZ-Box-7590/835_Shared-files-and-printers-o...
Read more

psql: error: connection to server at "localhost" (127.0.0.1), port 5433 failed: ERROR: failed to authenticate with backend using SCRAM DETAIL: valid password not found

-
Image
ERROR psql: error: connection to server at "localhost" (127.0.0.1), port 5433 failed: ERROR: failed to authenticate with backend using SCRAM DETAIL: valid password not found Since Pgpool-II is a PostgreSQL proxy that works between clients and PostgreSQL servers, the authentication comprises two steps: Authentication between client and Pgpool-II Authentication between Pgpool-II and PostgreSQL servers Starting with Pgpool-II 4.0, Pgpool-II supports scram-sha-256 authentication. scram-sha-256 authentication method is strongly recommended because it is the most secure password-based authentication method. Solution 1 If PostgreSQL servers require  MD5  or  SCRAM  authentication for some user’s authentication but the password for that user is not present in  pool_passwd , then enabling  allow_clear_text_frontend_auth  will allow the  Pgpool-II  to use clear-text-password authentication with user to get the password in plain text form from the user ...
Read more

Keeping Your SSH Connections Alive: Configuring ServerAliveInterval and ServerAliveCountMax

-
Image
Maintaining a stable SSH connection is essential when working on remote servers. Disconnections due to inactivity can interrupt workflows and be quite frustrating. Fortunately, you can configure SSH to send periodic keep-alive messages, preventing your connection from timing out. Step-by-Step Guide 1. Open the SSH Client Configuration File Use your preferred text editor to modify the SSH configuration file. For example, with  vim : sudo vim /etc/ssh/ssh_config If OpenSSH is installed via Homebrew, the configuration file might be located at: /usr/ local /etc/ssh/ssh_config 2. Modify the Configuration Add the following lines after the  Host *  directive to apply these settings to all SSH connections: ServerAliveInterval 240 ServerAliveCountMax 10 ServerAliveInterval : Specifies the interval (in seconds) at which the client sends keep-alive messages to the server. In this case, every 240 seconds. ServerAliveCountMax : Limits the number of keep-alive messages sent w...
Read more