Jump to: navigation, search

Sahara/GitCommits

This document is a short tutorial with requirements and tips for committing to Sahara.

Git commit good practice

  • one "logical change" per commit:
    • don't mix whitespace/refactoring changes with functional code changes;
    • don't mix two unrelated functional changes (or functional with whitespace/refactoring changes);
    • don't send large new features in a single giant commit;
  • change request subject (first line of the commit message):
    • it should start from the upper case letter;
    • avoid usage of ':' in the subject (remember that it'll be displayed in the following form: "Change I1de3f893: Refactoring unit tests for validation");
    • avoid trailing punctuation;
    • it should be separated from the rest of commit message with empty line;
  • specify corresponding Launchpad bugs and blueprints in commit message:
    • bugs should be specified one per line in the following format: "Closes-Bug: #123456" or "Partial-Bug: #123456";
    • blueprints should be specified after blueprints one per line in the following format: "Implements: blueprint name-of-blueprint" or "Partially implements: blueprint name-of-blueprint";
  • make commit message clear:
    • 'Change-Id: IXXX' should be the last line and separated with empty line from the rest message;
    • separate bugs/blueprints with the empty lines before and after;
  • information in commit message:
    • the commit message must contain all the information required to fully understand & review the patch for correctness; less is not more; more is more;
    • do not assume the reviewer understands what the original problem was;
    • do not assume the reviewer has access to external web services/site;
    • do not assume the code is self-evident/self-documenting;
    • describe why a change is being made;
    • read the commit message to see if it hints at improved code structure;
    • ensure sufficient information to decide whether to review;
    • the first commit line is the most important;
    • describe any limitations of the current code.

Examples of good commit messages

TBD