Commit Message Guidance

The following is a DRAFT Request for Comment version of general guidance for PostgreSQL commit messages. The intent is:

1. Keep it simple and stay reasonably consistent with past practice.
2. Mirror similar guidance used by other open source projects, while maintaining the unique style of PGDG.
3. Enhance the ability to machine-parse the commit messages for the purposes of acknowledgement (release notes, contributor recognition, various efforts to recognize contribution, etc.)

General layout of commit message

<commit message>
 <summary line>
 <blank line>
 <narrative>
  <para></para>
  <blank line>
  <para></para>
  <blank line>
  ...
 </narrative>
 <tags>
  <tag>
  <tag>
  ...
 </tags>
</commit message>

Notes

• The gitweb commit summary line displays only 50 characters, and the Postgres email subject has only 64 characters, so try to stay under these limits. For a template, use:

  |--- gitweb subject length limit ----------------|-email limit-|

• When possible, the <attribution> should be a cut-and-paste of the attributed person's list email "From:" field, with no alterations.
• The format of tagged lines should always be the following, and should begin at the start of a new line:

 <tag>: <attribution> [(optional additional context in parenthesis)]

• If there are more than one attributed people for any given Tag type the "multiple tag lines" format should be used.

  multiple tag lines:
  <tag>: <attribution>
  <tag>: <attribution>

• The ordering of the <attribution> data should be approximately from "most significant participant" to "least significant participant".
• Tagged lines should be after the narrative portion of the commit message.
• Verbose extra context regarding the tagged items should be included in the narrative portion. Short context may go in parenthesis on the tag line as shown.
• If the committer is also the sole Author, the "Author:" tag may be omitted and the committer is therefore assumed to be the Author.
• When including themself in an <attribution>, the committer should spell out their attribution exactly as it appears on the "From:" field of their emails to the list, as they would for any other attributed person. The use of "by me" or other references to themself as "me" is discouraged in the tags section, but is fine in the narrative section of the commit message.

Tags: "<tag>:"

• "Reported-by:"
• "Suggested-by:"

 Used to credit someone who found the bug that the patch attempts to fix or suggested the feature that it adds.

• "Diagnosed-by:"

 Helped determine the root cause, but stopped short of authoring the patch.

• "Author:"
• "Co-authored-by:"

 Used to indicate the patch authors.  "Co-authored-by:" is used by committers when they want to give full credit to the named individuals, but also indicate that they made significant changes.

• "Reviewed-by:"

 Reviewers of the patch that performed a detailed analysis.

• "Tested-by:"

 Applied the patch and found it to have the desired effect.

• "Bug:"

 Bug number with number sign

• "Discussion:"

 A URL pointing to the mailing list discussion resulting in the patch. Ideally should point to a relevant message using the https://postgr.es/m/MESSAGE_ID URL format.

• "Backpatch-through:"

 The oldest stable branch to which the patch was applied. This should be the major version number only, e.g. "15" (without the quotes), and should be skipped for master-only commits.