Skip to content

Commit message format

Jump to bottom
Richard Smith edited this page Mar 25, 2020 · 6 revisions

Commits from committee papers

For a commit that incorporates a N paper, P paper, LWG issue resolution, CWG issue resolution, or editorial NB comment resolution, commit messages for these take the form:

<paper description>

<description of deviations from paper wording and editorial changes, if any>

<also fixes list, if any>

The paper description should be one of these:

  • N1234 Title From Paper
  • P1234R5 Title From Paper
  • LWG1234 Title from issues list
  • CWG1234 Title from issues list
  • NB US 123 (C++14 CD): <editorial change description>

These commits should be placed on a branch corresponding to the relevant motion, which has a name of the form motions-YYYY-MM-cwg-XX or motion-YYYY-MM-lwg-XX for core and library motions (and -sg1- for SG1 motions, if they ever make more), where YYYY-MM is the year and month of the plenary session in which the motions were moved (typically the Saturday of the meeting), and XX is the motion number.

Editorial commits

The commit message for an editorial commit should be simply an <editorial change description>. This has the form:

[section.label] What I changed in this section and (briefly) why it's editorial if that's not obvious

If multiple section labels are changed in the same way, list multiple labels separated by ", ":

[here], [there], [elsewhere] Do stuff.

If the change affects the entire standard, the section label can be omitted, and the message should instead say the changes apply throughout the standard.

Our commit messages are used as a change log in Editors' Reports, so please keep that in mind when writing them. In particular, the commit message should first describe what change you made, not why you changed it or what problem the change is fixing or the effect the change is trying to produce. (You may include such details later in the commit message if you feel they are important and not obvious.) Bad:

[expr.widget] Widgets aren't pink.

Better:

[expr.widget] Fix note that suggests that widgets could be pink.

Motion merge commits

When merging a motion into the draft, a merge commit is always created even if a fast-forward would be possible. The second parent is the merged motion, and the commit has a message of the form

Merge 2016-11 CWG Motion 1

Additional description can be provided if there were merge conflicts that needed resolution.

"Also fixes"

A commit that implements a paper / issue resolution might also have other effects, such as resolving additional issues, one or more national body comments, and/or some github issues. If so, end the commit message with:

Also fixes #4, #17, NB US 123, GB 45 (C++ 14 CD), CWG56.

Put the issue numbers (#4, #17) first so that github knows to automatically close those issues. Use "Fixes" instead of "Also fixes" for a purely editorial commit.

Clone this wiki locally