Guidelines for syntax of titles in GitHub issues and pull requests?
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 25/100
- Issue type
- Documentation
- Clarity
- Needs clarification
- Activity status
- Stale
- Tech stack
- github
- Domain
- documentation
Research direction
Start by reviewing the proposed issue and pull request title examples, the rationale for prefixes, and the existing discussion in this issue. No repository file or test is identified. The work would be complete when the project agrees on title recommendations and the draft’s Do and Don’t guidance is finalized.
Written by the indexing model from the issue text.
Description
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 modulesGeneral 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
- Dominant language
- HTML
- Stars
- 148
- Forks
- 41
- Avg merge
- 1m
- Merged PRs (30d)
- 2
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from w3c/w3c.github.io
-
Difficulty 1/5 Under an hour Newbie friendliness 35/100
w3c/w3c.github.io#93 · 1 comment ·
-
Difficulty 1/5 Under an hour Newbie friendliness 45/100
w3c/w3c.github.io#92 ·
-
Difficulty 5/5 Over a week Newbie friendliness 20/100
w3c/w3c.github.io#91 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 35/100
w3c/w3c.github.io#78 · 5 comments ·
-
Difficulty 5/5 Over a week Newbie friendliness 15/100
w3c/w3c.github.io#70 ·
All issues in w3c/w3c.github.io
Similar issues
-
sync-en
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Maintainers usually reply within 3 days
-
documentation hermes-queue
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
chrisalunlloyd2-sudo/mindpalace#294 ·
Maintainers usually reply within 1 day
-
Refresh stale docsOpen
Difficulty 1/5 1-3 hours Newbie friendliness 67/100
OpenCarControls/firmware#35 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
-
[integration]: DefrrOpenexternal integration integration-submission
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
langchain-ai/docs#6950 ·
Maintainers usually reply within 1 day