Page History
...
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
...