Making a good pull request message

This is a brief guide to pull request messages for the WRF repository.

To start, here is the template that is provided when you start the process of opening a pull request (can also be found in the WRF source code under tools/commit_form.txt):

The first line should be a single-line "purpose" for this change

TYPE: choose one of [bug fix, enhancement, new feature, feature removed, no impact, text only]

KEYWORDS: approximately 3 to 6 words (more is always better) related to commit, separated by commas

SOURCE: Either "developer's name ( and affiliation)" .XOR. "internal" for a WRF Dev committee member

DESCRIPTION OF CHANGES: One or more paragraphs describing problem, solution, and required changes.

ISSUE: If this modification addresses an "issue" then it should be referenced here. This will let GitHub know that it can mark the issue as complete. (e.g., "This issue fixes #123," where 123 is the issue number).

LIST OF MODIFIED FILES: list of changed files (use `git diff --name-status master` to get formatted list)

TESTS CONDUCTED: Explicitly state if a WTF and or other tests were run, or are pending. For more complicated changes please be explicit! It may help to include plots.

RELEASE NOTE: If relevant, you may type here the important information that should go out to users in the code release notes. This should be brief, but descriptive, and should read exactly as this will appear to users from the official release notes.

It's a bit descriptive, but it might not tell you everything you need to know. Below we will go over what should be listed in each section, and give an example from previous "good" pull requests.

Title

Every pull request needs a title. Titles should give people a good idea of what your code change will do in approximately 5-15 words. They should be as precise as possible, so people can already have some idea on whether they are interested in the changes from the title alone.

Some good examples from the past:

All of the above do a good job of concisely describing the changes contained in the pull request: they are not too wordy so that the title gets cut off in various emails and web pages, and not too vague so that it's unclear what part of the code is being changed.

In contrast, here are some made-up (but plausible) examples of BAD pull request titles:

Bug fixes (Bug fixes on what part of the code?)
Changes to surface scheme (What kind of changes? What surface scheme?)
Add new scheme

TYPE:

The "type" of pull request you are opening is a descriptor of the general impact your change will have on the code. You should choose one of the following options:

bug fix

Fixing a demonstrably incorrect portion of code (this is the only type that should be committed to the bug fix release branches, e.g., release-v4.1.1)

enhancement

Changing an existing portion of the code; though the old code was not unambiguously wrong, this change presumably improves the code

new feature

Adding a new feature to the code

feature removed

Removing an existing feature of the code. This one has yet to ever be invoked I'm pretty sure.

no impact

For display changes such as changing the "version_decl", changing variable names, improving error messages, changing quoted Registry elements, or otherwise changing what appears in the log/out/error files but not impacting history/restart output results, timing performance, or memory footprint.

text only

For README and comments, changing quoted Registry elements, white space alignment, or other changes which have no impact on program output or log files. Ultimately, any change which does not impact the compiled code in any way should fall under this category.

KEYWORDS: