Commit and PR message template
In order to have a clear, readable record of changes made to the E3SM source, its essential for all commit messages to have a similar style and content.
Your commit messages appear in the git log and "the git log is forever". That is, even if the E3SM project, or github go away, the git log with your commits and your name on them will always be there as a record of what happened (assuming your branch gets merged to master). So treat your commit messages with care.
The description of a github Pull Request (PR) will be used as the message for the merge commit for the branch so all PR descriptions should follow these rules.
Commit messages should have a title AND a body. Just repeat the title for the body if you can't think of anything to add.
The title should completely describe the change within its character limits. e.g. "Add new evaporation scheme", "Fix convection bug". Do not continue the title in to the body.
Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated
by commands like git merge and git revert.
It is understood you are talking about the commit or PR. Do not start with "This commit...." or "This PR will...".
Keep the body brief. Just a few sentences. For PRs, use the comments after the description to add more detail if you want.
Do not substitute github issue numbers for descriptions of what you are fixing or doing or use github issue numbers in the title. "Fixes #999" is not a good commit message or title. Imagine that GitHub goes away someday. The commit messages in our git repo should still make sense. Reference issue numbers at the end (the "Fixes" lines) or parenthetically.
Do not include URL's to Confluence or other web sites in the commit message to explain what you're doing. DOIs are ok. For PR's, add more detail after a line in the PR description or use the first comment.
Commit message or PR description
one-line explanation of commit less than 70 characters
After a blank line, write a more detailed explanation of the commit.
Many tools do not auto-wrap this part, so wrap paragraph text at a
reasonable length. Commit messages are meant for other people to read,
possibly months or years later, so describe the rationale for the change
in a manner that will make sense later. You might be the one puzzling over
the commit months later so write it for your future self.
DO NOT LEAVE THE BODY BLANK. Just repeat the title if you have to.
The message should prominently state its impact on users, such as a
different interface or a change of bit-for-bit results.
* Commit messages may contain lists.
* Commit messages should NOT contain URLs to Confluence or any other web site within the main body.
Our Confluence is mostly private so it will not help to explain the public commit message.
Commit messages are forever but URLs can break or go stale. Put URL's with more info at the bottom. DOIs are ok.
* Following these guidelines improves the ability of tools to quickly
summarize changes according to various criteria.
If other people contributed significantly to a commit, perhaps by
reporting bugs or by writing an initial version of the patch,
acknowledge them using tags at the end of the commit message.
Reported-by: Helpful User <helpful@example.com>
Based-on-patch-by: Original Idea <original@example.com>
Thanks-to: Incremental Improver <improver@example.com>
Describe changes in less than 70 characters in title.
If this affects any known issues, include "see #ISSUENUM" in the message (without quotes).
GitHub will create a link to the issue as well as a link from the issue to this commit,
notifying anyone that was watching the issue. Do not put "Fixes" because that is reserved
for the merge commit to master (which actually fixes the bug).
Add the following tags as appropriate:
[BFB] or [non-BFB] or [CC] !! Add at least ONE of these keys to indicate how this commit will affect testing against baselines.
!! [BFB] means all output from tests will be bit-for-bit (BFB) identical with the baselines.
!! [non-BFB] one more more tests will not be BFB with baselines. You can specify the tests. You can also
!! use [non-BFB] and follow it with a description of what cases will be non-bfb.
!! [CC] the commit will change the climate of one or more cases under test.
[FCC] !! Also add [FCC] if the commit will change climate if a flag is activated.
[NML] !! Also add [NML] if the commit introduces changes to the namelist.
AG-67, AG-56 !! On the last line, optionally add JIRA issue numbers for issues this commit is satisfying if available.
See also https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
Merge commit messages (For Integrators when merging to "next" OR "master" OR "maint")
Merge branch <branchname> (PR #10) !! Add the PR # to the automatically generated title. Leave "into next" in title when merging to next.
!! Add "into maint-1.0" for maintenance branch commits. Don't worry about going over the 70 char limit.
(Be sure to add a blank after above title)
(copy and paste the original description from the PR. It may already have the content below.)
(copy and paste the testing description in the PR and add info on any more testing done prior to merging)
Fixes #XY, Fixes #MN (include Github issue numbers for the bugs this commit fixes. Be sure to use the word "Fixes"
before each # to close the associated bugs)
[BFB] or [non-BFB] or [CC] !! Add ONE of these keys to indicate if this commit will affect testing results to roundoff [non-BFB]
!! or climate changing [CC]. Use [BFB] if-and-only-f commit is bit-for-bit and
!! you know all the tests will pass without regenerating baselines.
[FCC] !! Add [FCC] if the commit will change climate if a flag is activated.
[NML] !! Add [NML] if the commit introduces changes to the namelist.
(If the merge produces merge conflicts, the list of files that were in conflict should be left in the message.)