Skip to content

[meta] Add guidance for how to write good new issues #12200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
justinfagnani opened this issue May 15, 2025 · 1 comment
Open

[meta] Add guidance for how to write good new issues #12200

justinfagnani opened this issue May 15, 2025 · 1 comment
Labels

Comments

@justinfagnani
Copy link

For people who aren't regular contributors here it would be really useful to have some guidelines on how to open a good issue.

There is a lot of variation in issue titles, though an obvious common structure for most of them. Non-working group members might not know what categories to use, or whether a member will clean up the title later if it gets discussed.

Should new issues include a prefix like [proposal] or [idea]? Should "proposal" be used informally, or is it a more formal term here that includes specific choices fora change?

Likewise, with so many issues it's common for other repositories for new issues to include the search terms they used to try to find an existing issue first.

There could be an issue template, or just guidance on https://github.com/w3c/csswg-drafts/blob/main/CONTRIBUTING.md

@kbabbitt kbabbitt added the meta label May 19, 2025
@kbabbitt
Copy link
Collaborator

My observations:

  • The only consistent convention I've seen with issue naming is to prefix with the shortname(s) of the relevant spec(s) in brackets. One might argue that GitHub tagging is a cleaner way to relate issues to specs, though I do find it convenient to have shortnames in issue titles when I'm scanning email notifications.
  • I've seen issues that introduce new ideas or features both labeled "Proposal" and not. It doesn't appear to have a specific meaning other than when it's used to introduce a "proposed resolution" meaning "thing the author would like the working group to resolve on."

I think a "good issue" contains the following elements:

  • Link to and/or quote of relevant existing spec text, where applicable
  • Description of what the author would like added, clarified, or changed, and why
  • Suggested changes if the issue author has something in mind already
  • Markup snippets / test cases / example renderings are usually quite helpful

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants