-
Notifications
You must be signed in to change notification settings - Fork 663
How to Write a Good Issue
All great projects are built on user feedback. In the case of this repository we use GitHub issues to track feedback. This page details how to write an issue that is easy for a developer to read and respond to, which makes it more likely that your bug report/feature request will be adressed!
So you think you've discovered a bug, that's awesome! We love hearing bug reports because we want this project to be as stable as possible. Here are some steps you can follow to help your bug get fixed.
If you've stumbled upon a bug, it's likely that someone else has found it as well. Before putting the effort into writing an issue, do a search to see if someone else has reported it.
If you do find a matching issue, feel free to give it a thumbs up 👍 or add a comment detailing how this bug is affecting you. If developers see that a bug has a high impact, it's more likely to get fixed.
A bug is only fixable if it is reproducible, so before you submit an issue, make sure you have a solid way of getting your bug to occur.
You should end up with a numbered list of steps that tell a developer how to reproduce the bug. For example:
- Open X codelab.
- Go to Y page.
- Run Z example code.
- Observe the bad behavior.
If you think your bug is related to plugins, be sure to check the cause before submiting your issue. Just because you're using Blockly plugins, it doesn't mean a bug is caused by those plugins. You may have stumbled upon a bug in Blockly itself! Try to reproduce your bug in the playground. If you can, go ahead and submit your issue in the Blockly Core repo.
Generally, the more information your bug has: the better. Here are a few things you might want to provide.
- Screenshots or Gifs can be really helpful if a bug causes a visual problem.
- Sample Code is useful if a bug only affects certain kinds of blocks, or configurations of workspaces.
- A Hosted Site is great if you're having trouble reproducing your bug outside your specific environment.
You should now be prepared to write your glorious bug report. Be sure to fill out all the sections of the issue template, even the ones that aren't detailed here. As you do, try your best to be concise! People want to help you fix your bug, but if they have to read your memoir to find the issue, that can be harder.
Thank you for your interest in reporting a bug, and happy issue writing!