Now that the GlassFish 4.0 project is using the change control process
for fixing the remaining bugs, it is more important then ever to have
good commit messages when code is submitted to SVN. Please see this page
for the expected content for commit messages and other information about
checking in a fix:
https://wikis.oracle.com/display/GlassFish/CheckInBestPractice
The information from that page about commit messages is below.
Thanks.
Tom
Commit Messages
The commit message becomes part of the permanent record of the change in
the source code repository. These messages are available to any
developer using the "svn log" command and are shown in the "recent
changes" section of Hudson jobs. Good commit messages can greatly
enhance the ability to review past changes to the code.
What questions does a person want to be able to answer by looking at the
commit messages, and what does that in turn imply about what must be
included?
* Why was this change made? Formal bug identifier? Feature
requirement? FindBugs fix? Copyright date correction? We can't link
every check-in - not today at least - to a JIRA or another issue
tracking system. When we can we should and when we can't the commit
message should briefly describe the problem being fixed or the
improvement being made.
* What's the general thought behind the solution or improvement?
* Who reviewed or approved the check-in?
* What tests did the engineer run before check-in? (Can in a few
cases be empty - for example, when updating a copyright date or a
comment)
For problems, the combination of the formal issue and the commit
message should explain:
* the outward bad behavior. (Typically, if there is an issue, then
this should be in the issue.)
* the underlying cause, (In either the issue or the commit message -
some people like to report their fact-finding in the issue as they
work through it, some save it for the commit message), and
* the repair. (in the commit message).
So given this, here is a template to use when writing commit messages:
|<issue-id or ||"no issue"||> - <summary of change>.|
|[Approved/reviewed by <name>.]|
|[Passed <list of test suites>.]|
The bugid should be something like GLASSFISH-12345, not a URL. Typically
only one issue should be fixed in a commit, but if multiple issues are
fixed, then use a separate line with a separate summary for each issue.
The summary of change may be multiple lines, especially if there is no
issue. This summary must at least include a high level description of
the changes that were made. If there is no issue, then this may also
include a description of what problem is fixed by the change. The name
should be the person's real name. The list of test suites can use
commonly known abbreviations like QL for Quicklook. The "approved" and
"passed" lines are optional but recommended.
Here is an example commit message that uses this template.
|GLASSFISH-||20056| |- Get the deployment order out of the map as a
separate step|
|before constructing the ApplicationOrderInfo. Also check ||if| |the
application|
|is already loaded before trying to load it in InstallerThread.|
|Passed QL, deployment dev tests.|
When using the -m option of the svn commit command, it is fine to put
all of this information on one line.