Message formats for committing code SVN
This page describes some guidelines when committing code to dCache.
ReviewBoard description
The ReviewBoard request has a summary and description.
The summary is a short meaningful description of the patch. The high-level area of dCache may be included a keyword followed by a colon as the first element. Here are some examples:
- dcap: fix broken handling of unicode
- pool: speed up recovery procedure
- scripts: better error reporting in dcache script
The description part of the request gives a more complete description of the problem. As a template, include the following information:
- brief description of the current situation,
- why this behaviour is wrong,
- how the patch addresses the problem.
The description may also include additional notes such as limitations of the patch.
SVN log file
The overall format is:
- a one-line summary,
- a more detailed description,
- some metadata: formatted as keyword-value pairs,
- optional release-notes part.
<one line summary> <more detailed summary> <which may be split over several paragraphs> Patch: <ReviewBoard URL> [Bug: <RT URL> ] [Signed-off-by: <name of person>] Acked-by: <name of person> Target: <commit branch> [Target: <another commit branch> [..]] [Request: <support branch> [Request: <another support branch> [..]] Merge-req: <RT URL>] [ RELEASE NOTES: <notes for whoever is collating the release notes>] [ DOC: <notes for whoever is updating the book>]
Summary and description
The one-line summary is the summary from the ReviewBoard request.
The more detailed description is the description from the ReviewBoard request.
Metadata
The metadata section is written with a specific format, which is described below. This format is to allow automatic parsing of this metadata.
Simple keyword-value pairs are written as independent lines like "keyword: value" with no space before the keyword; for example
Target: trunk
Some of the metadata may be a multiple-item list. If so, the values of the list should appear on separate lines, each with the same "keyword: " prefix; for example
Request: 1.9.5 Request: 1.9.8 Request: 1.9.9 Request: 1.9.10
Each patch should include a link to ReviewBoard. This information has the keyword "Patch". The value is the URL of the patch.
If the patch is to fix a specific support ticket (as recorded in RT) then information about which ticket should be included using the keyword Bug. The value is the URL of the RT ticket. This item may be repeated if the patch addresses several RT tickets. Remember to update the RT ticket when the patch is committed, stating into which branch(es) the patch was committed.
The normal process is for whoever submitted the code for review to finally commit the code. If this isn't followed, some other than the original patch writer is committing the patch. To indicate this, include the original author with the "Signed-off-by:" keyword. If the code has passed through several hands, the "Signed-off-by" is repeated, once for each person.
When committing, it is useful to know into which branch(es) the patch is committed. This is written using the Target keyword. The value is the common name for the different support branches (e.g., trunk, 1.9.5, etc).
Support branches are only updated by the Release Manager. If the patch is intended for a stable branch then a merge request should be created, which is indicated by the Request keyword. The value is the branch the developer is requesting the patch be merged into. The Request line is repeated for each requested support branch.
If a patch is requested to go into support branches then we want some way to navigate from the commit message to the merge request. This is the "Merge-req" keyword. The value is a reference to the RT ticket (the URL).
Release-notes
After the metadata section a commit message may include notes providing a high-level summary of the effect of the patch for end-users (sys-admins or users). This is to help whoever is building the release notes for a release. This section is prefixed by a line RELEASE NOTES:
Examples
gplazma: fix formatting of log4j appenders This patch fixes a bug in the formatting of the log4j appenders in gPlazma. The previous formatting acted on the parent console appender, which caused the formatting to remain in the log statements after the authorization had finished. The fix is to format each classes own log4j appender instead of the parent's. Acked-by: Timur Patch: http://rb.dcache.org/r/536/ Target: trunk
Another example, with back-port requests:
Scripts: Fix bug introduced in r10433. Patch #3874 intended to change the domain name of the domain hosting the admin door. It did this by changing the service name from admin to adminDoor and then relied on the automatic derivation of the domain name. A bug was introduced in that the service name was not updated throughout the script. Patch: http://rb.dcache.org/r/201/ Bug: http://rt.dcache.org/some-bug Signed-off-by: Gerd Acked-by: Owen Target: trunk Request: 1.9.6 Request: 1.9.5 Merge-req: http://rt.dcache.org/Ticket/Display.html?id=5811
Another example, with release-notes:
JettyGSIConnector: Automatically refresh host certificates/trust anchors Add setters for intervals in which trust anchors and host certificates should be reloaded. Reload if they are undefined or older than the given intervals. Acked-by: Gerd Behrmann <behrmann@ndgf.org> Target: trunk Patch: http://rb.dcache.org/r/2382/ RELEASE NOTES: The SRM door can now reload the host certificate and the trusted certificates (trust anchors) at configurable intervals. Between these refresh periods both the host certificate and the trusted certificates stay cached in the application. This should help the admin to avoid having to restart the service when host certificates or trusted certificates are replaced.
For ReviewBoard tracking
When closing the ReviewBoard entry associated with a patch, please update the patches description so it includes a list of which branches the patch was applied to.
The format is to write a line like Committed: <repository-id> for each branch the code is committed into. The <repository-id> has the form '<branch-name>@<revision>' for branches and 'trunk@<revision>' when committing into trunk.
Here's a message for a patch committed to the 1.9.5, 1.9.8, 1.9.9, 1.9.10 supported branches and trunk.
Committed: 1.9.5@1380 Committed: 1.9.8@1381 Committed: 1.9.9@1382 Committed: 1.9.10@1383 Committed: trunk@1384
