Draft guidance on how to write good commit messages

[ZoeBijl]

We need to document our preferred way of writing commit messages. This will allow everyone to write commit messages that are useful to us and that fit our style.

Example format:

Type: message (pull #001)

Type can be:

• Editorial
• Build Process
• Build Test Process
• Pattern Name (example: Button Pattern)
• Pattern Name Example(example: Date Picker Dialog Example)
• NPM Packages | Packages
• Regression Tests
• chore
• Pattern Name Regression Tests
• ??

Your message should be describing what the PR does, not what you did. It should also be relatively short. Try to keep it around 6 words.

✅ Add aria-labelledby to group of controls
⛔️ Added aria-labelledby to group of controls
⛔️ Adds a label to a group of controls via the aria-labelledby-attribute

[ZoeBijl]

@mcking65 I’ve drafted advice based on what I could extrapolate from our commits history over the last twelve months. Can you add anything that I might have missed?

[carmacleod]

@mcking65 @ZoeBijl
Do we want to take advantage of github's automatic closing of the related issue(s)?

If so, then either the commit message, or the PR description (personally I prefer to have this in the PR description) contains something like: Closes #1178.

Edit: Regarding my preference to have this in the PR description, I mean unless there's no PR, in which case adding it to the commit comment is fine.

[ZoeBijl]

I like that suggestion 👍. Would that mean an example PR title looks like: Button Example: add cute kitten image (Closes #420)?

[mcking65]

I authored a first draft on this wiki page about protected branch management. This page falls under management and operations in the wiki sidebar.

[carmacleod]

@ZoeBijl

Would that mean an example PR title looks like: Button Example: add cute kitten image (Closes #420)?

My preference is to put it in the description comment for the PR (i.e. the initial comment). The issue-closing magic would work if Closes #420 is in the title, but I think it kind of clutters up the title.
I believe the magic also works if Closes #420 is added to any comment, but (again, personal preference) I like it in the initial comment so that it's easy to find.

@mcking65
Do you prefer the word "Resolves" instead of "Closes"?
(either one will work but I noticed that your draft wiki page uses "Resolves").

Note that I'm not sure whether having the word "issue" between the keyword and the issue number will automatically close the issue when the PR is merged - we would have to try it.
(i.e. Resolves #420 will work, but Resolves issue #420 may not).

[ZoeBijl]

The documentation for closing words makes me think the number needs to follow the word directly. Because it doesn’t have examples of other uses.

Also, yes, having it in the content makes a lot more sense 🤦‍♀ .

[mcking65]

completed. See Protected Branch Pull Request Management and Merge Process · w3c/aria-practices Wiki