Best Practices: Github Issues

Note: This is a work in progress document.

Priority 1: Capture it in any way you can

• If you're in a hurry, some information is better than none. Get down the info you can.
• Try setting a Slack reminder to come back and add more information.
• At minimum, try to provide a brief description and a link to where you see the issue.

Priority 2: Document the information you know

• Prefix the title with what the type of item is. For example, use Block: Programs to describe the requirements for a Programs Gutenberg block.
• Add information that helps give someone else context. For example, if you have a mockup or screenshot, add it to the issue. Github now also supports video, which is great for demonstrating a bug.
• Add any requirements you can think of. Try to imagine different scenarios - what happens when there is more than one or not enough of a certain item? Is there certain data, like a calendar connection, you need? What order should things be in?

Priority 3: Have conversation and refine requirements

• The original issue description should be your source of truth.
• Use comments to talk through and discuss changes.
• Once a change is accepted, be sure to add it back to the official requirements by editing the original issue!

Getting information vs. assigning a task

Assigning a task in Github means that that person is responsible for doing the work for that task. Assignees should not be used for getting input or gathering information from ACDs, etc. Use the "needs" label for getting feedback instead.

• Use the "needs" label for stakeholders.
• Use the "assignee" area for managing who owns a task. Multiple people can own a task.