READING / concepts/commits-and-branches.md

A published OKF snapshot. Follow the map, then read at your pace.

Knowledge mapSee how this bundle connects3 concepts · No internal links yetOpen mapHide map

Nodes are colored by OKF type. Add internal markdown links to reveal relationships.

conventionunverifiedstable

Commits and branches

Commits

Imperative mood, under 72 characters: "Add retry to webhook delivery".
One logical change per commit. If the message needs "and", it wants two commits.
Never commit secrets, generated files, or lockfile churn from unrelated work.

Branches

Name by intent: fix/webhook-retry, feat/semantic-search.
Branch from the default branch; rebase onto it before opening a PR.
Short-lived branches. Anything older than a week should ship in slices.

Agents and git

Agents may stage files and create commits when asked, but must:

Show git status and the diff before committing.
Only stage files relevant to the task - never git add -A blindly.
Refuse to force-push, rewrite shared history, or delete remote branches without an explicit human instruction.

Merge policy

Squash-merge feature branches. The squashed message follows the commit rules above, so the log stays a readable changelog that agents can search later.