Git Conventions

Git Conventions

Types and scopes are defined in CONTRIBUTING.md#conventions — that file is the source of truth, read it before composing either.

Branch name

<type>/<scope>/<short-description>

• Top-level scope only — nested scopes are NOT allowed in branch names.
• <short-description>: kebab-case, concise.
• Total length ≤ 50 characters.

Commit message

<type>(<scope>): <subject>

<body>

• Determine type and scope from git diff --cached.
• Header: ≤ 72 characters. Nested scopes are allowed, comma-separated: fix(build, stapel, import): ….
• Subject: imperative, lower-case, no trailing period.
• Subject of a feat/fix: the observed outcome, never the mechanism. CHANGELOG.md is generated from these subjects verbatim, so the reader is a werf user who has never seen the code: name the symptom that goes away or what becomes possible, and leave function names, internal identifiers and the how to the body. make service script executable regardless of umask describes the patch; stop stapel builds failing under a custom umask describes what the user hit. For refactor/test/chore the reader is a developer and the mechanism is the right subject.
• Body: imperative; state the motivation for the change and contrast it with previous behavior. This is where the mechanism and the root cause go.
• NEVER include sensitive or customer-identifying details: client/company names, internal hostnames or filesystem paths, private build tags or version suffixes, credentials. Describe environments generically.

Before starting work

• Create the topic branch BEFORE the first commit, not before the push. main, 3, 2, 1.2 are release branches: a commit landed on one has to be moved by hand afterwards and its message amended along with it, and until someone asks for a PR nothing reveals it is on the wrong branch.
• git fetch and compare your base against origin/<base> BEFORE writing code, not at push time. A moved base can have refactored the very file you are about to edit, and the whole diff then has to be re-ported by hand during the rebase.

Before staging

• Re-check git branch --show-current immediately before EVERY commit, not just before the push. Worktrees here are long-lived and shared: another session can repoint the one you are standing in, and the first sign is your commit sitting on top of someone else's work, where undoing it means git reset --keep in a tree you do not own.
• Check git status for unrelated untracked files before staging. This worktree carries local working files (.dev/, scratch notes, orchestrator state), so prefer explicit paths over git add -A — a blanket add sweeps them in, and untracking later costs an extra commit. An orchestrator or helper commit command stages broadly — inspect git status BEFORE invoking it, not after.