Git Delivery

Git Delivery

A diff shows what changed. Delivery text records why, for a reader without the task's context: the reviewer now, and the maintainer reading git log or git blame years later. Write plainly and specifically; reviewers distrust generic, inflated text. This skill grants no authorization: commits, pushes, hosting writes, and merges still need the authorization the governing rules require.

Read examples.md for annotated messages from the Git, Linux, Google, and Conventional Commits guidance when shaping a body, a PR description, or a review reply.

Before writing

First, every time, even for a one-line change: run git log --no-merges -n 20 -- <touched paths> and read the contribution guide and PR template if present. When you present a draft, name in one line the convention you followed and where you found it.

1. The repository's subject prefixes, trailers, and body style override the defaults below, which apply only when the repository shows no convention. Supply required metadata (sign-off, issue or release links, AI disclosure) only when it is true; never invent identities or reviews, or carry one repository's requirements into another.
2. Identify the comparison base and destination separately (fork, release branch, an existing PR's base). Check that the commit identity and hosting account fit this repository; report a mismatch instead of editing Git config.
3. Inspect what is actually delivered: the final staged diff for a commit; every commit plus the full diff against the base for a PR. Describe that, not the task title or an earlier attempt.
4. Collect what the diff cannot show from the task and existing observations: the problem and its user-visible impact, why this approach, costs and side effects (with numbers when measured), constraints, and rejected alternatives a reader would otherwise propose. Keep observations separate from inferences. If the purpose is unclear, ask instead of inventing a reason.

Commit messages

• Subject: the repository's prefix convention (area:, type(scope):), defaulting to Conventional Commits; imperative, aiming at 50 characters with 72 as the ceiling.
• Body: omit it when the subject and diff say everything. Otherwise describe the problem as it exists without the change, why this change solves it, and side effects, costs, or compatibility consequences. Leave out line-by-line mechanics and how the problem was found.
• Summarize the relevant point of an issue or discussion instead of only linking it. Cite another commit by abbreviated hash and subject.
• Trailers go last, in the repository's format (Fixes:, Refs:, Signed-off-by:, BREAKING CHANGE:). Name other people in credit trailers only as the repository's policy allows.
• Notes meant only for current reviewers, such as changes since the last round, stay out of the message.
• Pass the message with git commit -F <file> or one -m per paragraph, never an editor or literal \n. Never bypass hooks (--no-verify, -c core.hooksPath=...) without the user's authorization. If a hook rejects the commit, nothing was committed: fix the cause and commit again, since --amend would rewrite the previous commit.

Pull/merge requests

The description informs the reviewer now and often becomes the squash-merge message. Before opening one, check for an existing open PR for the same branch or issue.

• Title: a commit subject for the whole change.

• Body: lead with the changed behavior and its effect, then only what helps a reviewer judge it. Follow the repository template when one exists; check only boxes that are true. Otherwise pick the smallest shape that fits:

  Change	Include
  Small or obvious	One paragraph, no headings.
  Bug fix, feature, refactor	Behavior and effect; root cause or non-obvious approach if any.
  Contract or breaking	Affected interface, before/after, compatibility, migration.
  Operational or visual	User or operator effect, measured impact, rollout, screenshots.
  Broad or cross-cutting	Why the breadth is necessary and where review should start.

• Do not add default Summary/Changes/Test Plan headings, pasted commands, CI logs, commit lists, or exhaustive file lists. Replace internal process terms (plan steps, task numbers, agent names) with the behavior they refer to.

• Verification: report checks that establish behavior or coverage, against which revision and platform; skip routine lint and formatting. A build does not show runtime behavior; a unit test does not show the user workflow. Once the relevant code changes, an earlier result is historical: rerun it, or label it and say what remains unverified. Do not describe a change as live before it is deployed.

• Closing keywords (Fixes #123) only for a verified issue in the target repository that this change resolves; Refs only links.

• Write the description as if the final diff had been written in one pass: state what is excluded and why, without who asked for it or how the branch evolved. When later commits change scope, approach, risk, or migration, rewrite title and description to match, and summarize changes since the last review in a comment. Typo-only or formatting-only follow-ups need no rewrite.

• Pass multiline text from a file or structured argument (e.g. gh pr create --body-file). Keep the configured Git transport and identity; do not switch them to work around a failure.

• Review the exact outgoing text before publishing: no internal identifiers, private paths, raw logs, or anything not already public in that repository.