Commit Hook Proposal

The vote to add a Subversion commit hook to enforce JIRA ids in commit messages was proposed in this thread on the dev@qpid.apache.org mailing list.

On 14 Feb 2011, at 16:53, Robbie Gemmell wrote:

add a pre-commit hook to enforce
use of JIRA references where appropriate. One suggestion I made was
that this would block all commits that don't have a Qpid JIRA
reference unless they instead contained eg 'NO-JIRA', which could be
used to bypass the hook on demand. Any commit which failed to meet
these cases would be rejected with a message alerting the committer
how to resolve the issue, i.e. include a JIRA reference if appropriate
or signal their intent to bypass the requirement. This means noone
would ever be prevented from committing what they want when they want,
but still removes the possibility of JIRA references being left out
due to merely forgetting them, and means that if/when we later review
the commits we can identify where people have chosen to purposely
bypass the requirement.

The following section suggests a standard format for commit messages for the Qpid project.

Commit Comment Formatting

We SHOULD (see RFC 2119 for meanings of bolded words) standardise the formatting of the rest of the commit comments too, albeit without automated enforcement. I suggest the following:

QPID-0000, QPID-0001: Summary of contents of commit

Description of contents and purpose of commit. Any other details of commit go
here, such as issue summary and how or why this commit fixes it. Complex issues
and rationale belong in JIRA comments, however. Related issues are referenced
by id only, as PROJECT-0000.

Contributed by Person One <person.two@example.org>
Contributed by Person Two <person.two@example.org>

In JIRA commit comments the JIRA id MUST appear as the first characters on the first line and MUST be formatted as QPID- followed by the JIRA number in decimal. This MUST be a valid Qpid JIRA id from the ASF JIRA site. If multiple JIRA ids are referenced, they should be separated by a comma and a space and kept together at the start of the first line. There MUST be a colon and a space immediately following the JIRA id(s).

The summary on the first line SHOULD be a grammatically complete sentence, but MUST NOT be terminated by a full-stop or period.

In all comments a full description of the purpose of the commit SHOULD be added after the summary and MUST be preceded by a blank line. The description MUST consist of paragraphs of text with lines no longer that 80 characters. Each paragraph MUST be separated by a blank line. The comment text MUST NOT contain JIRA URLs from the ASF JIRA site. If other ASF JIRAs are referenced, only the JIRA id MUST be used and MUST be formatted in the same fashion the Qpid JIRA id(s) at the start of the first line.

In all comments, contributors other than the committer MUST be identified by a valid e-mail address surrounded by angle-brackets and be preceded by their full name. Multiple contributors MUST be listed on separate lines. Contributor lists MUST be separated from the description or summary by a blank line.

NO-JIRA: Summary of contents of commit

Full description of contents and purpose of commit. Any other details of commit
go here, such as issue summary and how or why this commit fixes it. Complex
issues and rationale belong in JIRA comments, however.

External reference <http://tracker.example.com/id>

In NO-JIRA comments, the first characters on the first line MUST be NO-JIRA and MUST be immediately followed by a colon and a space and a short summary of the commit. There MAY be an external reference to another bug tracking system which MUST be preceded by a blank line. The reference MUST show the full URL of the issue on the external site, surrounded by angle-brackets. The description MUST contain a complete explanation of the reason for the commit if there is no external reference.

NO-JIRA: Trivial commit description

In trivial NO-JIRA comments the description paragraph MAY be omitted.