wiki:CommitMessageFormat
Last modified 3 years ago Last modified on 11/11/15 16:42:18

Git commit message format

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:

  1. brief description of the current situation,
  2. why this behaviour is wrong,
  3. how the patch addresses the problem.

The description may also include additional notes such as limitations of the patch.

Git log file

The overall format is:

  • a one-line summary,
  • a more detailed description,
  • optional release-notes and book parts.
  • some metadata: formatted as keyword-value pairs,

Parts in square brackets are optional

<one line summary>

Motivation:
<describe why you want change the code>

Modification:
<describe changes was made>

Result:
<describe user visible changes>


Require-notes: <yes|no>
Require-book: <yes|no>
[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>]

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.

Each patch should include a statement about whether it merits a specific mention in the release-notes. This information has the keyword "Require-notes". The value is "yes" or "no". If the value is "yes" then some guidance should be provided in the "RELEASE NOTES" section. This doesn't need to be final prose, but should be sufficient for a non-coder to understand the impact of the change for administrators and end-users.

Each patch should include a statement about whether the Book needs to be updated. This information has the keyword "Require-book". The value is "yes" or "no". If the value is "yes" then some guidance should be provided in the "BOOK" section. This doesn't need to be final prose, but can provide guidance of the different parts that should be documented.

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).

Examples

Motivation:

Currently we have a mechanism for injecting a custom executor into the cell
nucleus to be used for message processing. This is used both to tune the
concurrency/queue limits of the cell, as well as to inject shared executors
to use accross several cells.

The problem with the current design is that it presents a problem with how to
initialize the custom executor: Initialization should be done on the message
executor to get the correct thread group and CDC inheritance, but that means
a custom executor should be created before regular initialization or we have
to first start on executor for initialization and then replace it with another
one. The latter is currently done for UniversalSpringCell.

Modification:

With this patch a bounded executor is used for message delivery and cannot
be replaced. The thread and queue limits are however configurable through
cell arguments. Since a bounded executor wraps another executor, a shared
executor can be realized by letting multiple cells wrap the same executor
(this is done by the line based door).

The cell message executor is exposed to the spring configuration to allow
cell components to execute tasks on it.

Result:

Significantly simpler message executor design and no duplicate executor
creation during startup. The configuration properties for setting the limits
have been harmonized and the old names have been deprecated.

Target: trunk
Require-notes: yes
Require-book: yes

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 'masterk@<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: master@1384