Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Reduce summary line to 62 characters, improve description of commit hooks

...

The first line of the commit comment is the commit summary of the change. Changes submitted to the fs/lustre-release branch also require a Lustre Jira issue tag ticket number at the beginning of the first line of the commit summary. A Lustre Jira ticket is one that begins with LU and is therefore part of the Lustre project within Jira. If the patch is submitted for the fs/lustre-release repository without a Lustre Jira ID in the first line, then it will automatically receive a -2 review which will prevent the patch from being submitted to a release branch. You will get an e-mail about this rejection at which time you can add the would then need to fix the summary line and resubmit the patch.

The commit summary should also have a component: field tag immediately following the Jira issue tag ticket number that indicates which Lustre subsystem that the commit is related to. Example Lustre subsystems relate to modules like: llite, lov, osc, mdc, lmv, ldlm, ptlrpc, mds, oss, mdd, osd-ldiskfs, ldiskfs, lnet, libcfs, socklnd, o2iblnd; functional components like recovery, quota, grant; or auxiliary components like build, tests, iokit, docs. This subsystem list is not exhaustive, but provides a good guideline for consistency.

The commit summary line must be 62 characters or less, including the Jira ticket number and component tag, so that git shortlog and git format-patch can fit the summary onto a single line. The summary must be followed by a blank like. The rest of the comments should be wrapped to 70 columns or less. This allows for the first line to be used a subject in emails, and also for the entire body to be displayed using tools like git log or git shortlog in an 80 column window.

No Format
LU-nnn component: short description of change under 6462 columns

The "component:" should be a lower-case single-word subsystem of the
Lustre code that best encompasses the change being made.  Examples of
components include modules like: llite, lov, lmv, osc, mdc, ldlm, lnet,
ptlrpc, mds, oss, osd-ldiskfs, ldiskfs, libcfs, socklnd, o2iblnd;
functional functional
subsystems like: recovery, quota, grant; and auxilliary areas like:
build, tests, docs.  This list is not exhaustive, but is a guideline.

The commit comment should contain a detailed explanation of the changechanges
being made.  This can be as long as you'd like.  Please give details
of what problem was solved (including error messages or problems that
were seen), a good high-level description of how it was solved, and
which parts of the code were changed (including important functions
that were changed, if this is useful to understand the patch, and
for easier searching).  Wrap lines at/under 70 columns.

Signed-off-by: Your Real Name <your_email@domain.name>
Change-Id: Ixxxx(added automatically if missing)xxxx

The Change-Id: line and Code Style

Gerrit will needs to automatically identify updates to existing patches and update the existing request change instead of creating a new one for each patch submitted. This preserves the history of patch comments, and allows comparing old and new versions of a patch for more efficient inspections. For this to work properly the changes you create locally need to have a unique commit id in them.

Please make sure the Change-Id: line and Signed-off-by: lines are at the bottom of the comment. This is required by the fs/lustre-release project (at least) in order for the patch to be approved. If your comments are missing either of these lines the patch will be automatically be rejected at submission time.

To get the The Commit-Id: field is inserted automatically , link into the commit message by installing the build/commit-msg hook into each Git repository's .git/hooks/ directory. This will update the commit message for changes you commit to your repository before they are submitted to Gerrit. The commit-msg hook will also verify that the commit message format matches the format specified above. Similarly, linking the build/prepare-commit-msg script into .git/hooks/ will run the build/checkpatch.pl script against each patch at commit time to check it against the Lustre Coding Guidelines. should be installed as well. From the top-level Lustre tree checkout:

No Format
ln -sf ../../build/commit-msg .git/hooks/
ln -sf ../../build/prepare-commit-msg .git/hooks/

For older Lustre versions that are missing these commit hooks, they can be copied from a newer branch of Lustre (e.g. master)At git commit} time this will run the {{build/prepare-commit-msg script from the currently Lustre tree to check the code changes for style errors using build/checkpatch.pl, and add comments at the bottom of the commit message with any warnings or errors. After the commit message has been saved, the build/commit-msg script will verify that the commit message format matches the format specified above, and insert the Commit-Id: field into the commit message, if one isn't already present.

Additional commit tags

A number of additional commit tags can be used to further explain who has contributed to the patch, and for tracking purposes. These tags are commonly used with Linux kernel patches. These tags should appear before the Signed-off-by: tag.

No Format
Acked-by: User Name <user@domain.com>
Tested-by: User Name <user@domain.com>
Reported-by: User Name <user@domain.com>
Reviewed-by: User Name <user@domain.com>
CC: User Name <user@domain.com>
{Organization}-bug-id: arbitrary bug Arbitrarytracking identifier
No Format
The {Organization}-bug-id: tag can be used to track this patch in other bug databases (e.g. bugzilla or internal bug databases).

Examples of good commit comments

...