User:8680/GitGoodPractice

Commits

• A commit should be, to quote shadowm, “sufficiently self-contained that it can be reverted […] without leaving any related changes behind”.
  • A commit to a long-running (or otherwise non-topic) branch should work on its own, without requiring subsequent commits.
    • It’s fine for a commit to not work (or only partially work) if it’s a commit to a temporary topic branch, which is to be merged into (not fast-forward-merged into, or rebased onto) another branch when the commit series achieves full functionality.
      • Rationale: If someone is iterating through each commit in a long-running branch (say, the ‘master’ branch), it would be best if each commit iterated over works, or at least makes a good-faith effort to. From the iterator’s perspective, a branch properly merged into ‘master’ would appear as a single commit (the merge commit), but if that merged branch was fast-forward-merged/rebased, then it would be as if each (possibly non-functional) commit was made to ‘master’ separately.

Commit messages

• A commit message consists of a summary line and a message body, which must be separated with a blank line.
• The summary line should summarize the message body in such a way as to be as useful as possible for developers reviewing the commit history in the future.
  • The summary line should be written in “imperative present tense” — e.g., “Fix issue X”, not “Fixes issue X”, “Fixed issue X”, or “Fixing issue X”.
  • The summary line should be a sentence, except without a full-stop character at the end.
    • The summary line should be in sentence case — e.g., “Fix Latin translation”, not “Fix Latin Translation” or “fix latin translation”.
  • The summary line should be limited to 50 characters (or, rather, 50 columns; some characters can occupy multiple columns) or less.
    • shadowm professed to prefer an 80-character limit, but later clarified that that preference is not to be taken as policy.
• The message body should describe and explain the changes made in the commit, and the rationale behind those changes, as fully as possible.
  • The message body should be hard-wrapped to 72 characters (or columns).
  • The message body should be written in imperative present tense like the summary line, if feasible. Longer (better!) message bodies may be awkward or infeasible to write in imperative present tense; in such cases, it’s okay to write the message body in non-imperative present tense — e.g., “This commit fixes issue X, by making changes that I will now describe and explain in extensive detail.”.

Pull requests

• A pull request should always request the pull of a topic branch, never a long-running branch (like a ‘master’ branch).
• A pull request should be self-contained, like a commit should be.