Guidelines for syntax of titles in GitHub issues and pull requests?

[kaelig]

There are usage recommendations for GitHub labels. Should there be recommendations for issue and pull request titles? (editors on my CG was recently asking themselves this question)

Examples I've seen in the wild:

• [module-name] Discussion specific to a single module
• [module-name,other-module-name] Discussion related to multiple modules
• General discussion or question

Ideally, we'd document the reasoning behind these recommendations (see draft below).

Curious to hear what other folks think.

---

DRAFT Proposal:

Benefit of prefixes

Why use prefixes, when labels can do the same job? Both are useful, here are a few reasons to use prefixes in issue titles:

• [prefix] is a useful visual hint when scanning a long list of issues
• Facilitates plain text search
• Prevents duplicate titles across modules
• May be used by automations/bots
• When someone mentions an issue in a GitHub comment, issue, or PR, GitHub automatically expands the title, but labels aren't shown

Screen capture showing an issue without a prefix in its title. The user has to hover it to reveal the label, and understand that it has to do with the format module. Had it been prefixed with [format], the user would have immediately known about what module this issue touches on.

Do

todo

Don’t

todo

[dbanksdesign]

Very good points about the usability of the prefix. Maybe we can do prefix in the title for the module the issue is referring to, and use labels for the type of issue: question, bug, discussion, formatting, etc?

[plehegar]

+1 but only if the repo has multiple modules, such as https://github.com/w3c/csswg-drafts/issues. Otherwise it would simply be a repeat of what the repo is about. I feel that this needs to come in addition to Git Commit Msg conventions btw.

It may weel that we cannot link to a generic documentation here and have to create our own.