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. We do not use the a "ChangeLog" file that was in CESM. The "git log" command and good commit messages replaces the ChangeLog file.
The description of a github Pull Request will be used in the merge commit message for the branch so all PR descriptions should follow these rules.
All commit message 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. Do not continue the sentence in to the body.
The first sentence of the body should be passive and not contain a subject. It is understood you are talking about the commit or PR. Do not start with "This commit...." or "This PR..."
Do not substitute github issue numbers for descriptions of what you are fixing or doing. Imagine that GitHub goes away someday. The log messages in our git repo should still make sense. Reference issue numbers at the end (the "FIxes" lines) or parenthetically.
In addition to JIRA issue numbers at the bottom of the commit, you may, but are not required to, use other commands to manipulate the associated JIRA issue. See JIRA and Github linking.
...