-
Notifications
You must be signed in to change notification settings - Fork 663
How to Write a Good Issue
TODO: Add links to example & codelab guidelines once they exist.
❕ I feel like I might have gone a bit overboard. Do you feel like this page is too long?
🐙 The section on searching for duplicates is essentially duplicated. I would move it up to the top, and say that it doesn't matter if you're writing a question, bug report, or feature request.
❕ Also I'm thinking about changing the title to "Writing a Good Issue". Thoughts?
🐙 I like the current title better.
🐙 I would move "gather evidence" above "solidify your reproduction" and add it to the numbered list of steps.
🐙 I removed the section about memoirs that followed the instruction to be concise 🙂
🐙 Add a link to the page on adding a plugin somewhere, and say that it details the process that happens when you make a feature request for a new plugin.
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!
We love hearing your questions! But GitHub issues aren't a very good medium for them. If you have a question, head over to our developer forum instead. If you ask your question there you're more likely to get a timely and thorough response because it is filled with developers that have been using Blockly for years!
So you think you've discovered a bug? Great! 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 run into 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 find a matching issue, 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 submitting your issue. Just because you're using Blockly plugins, it doesn't mean your 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!
Thank you for your interest in reporting a bug, and happy issue writing!
Do you have an idea for a plugin, example, or codelab? Maybe there's already one you like, and you've come up with a way to improve it. If so then you've come to the right place! Here are steps to help you create a great feature request that gets a response.
If you've had an idea for an improvement, someone else might have had the same idea as well. Before taking the time to flesh out a feature request, do a search to see if anyone else has asked for something similar.
If you do find an issue you think matches, please give it a thumbs up 👍 or add a comment talking about how this feature would help your project. If developers see that a feature request is highly desirable, it's more likely to get worked on.
We would love to allow every single idea to enter this repository! But sadly we're only human, so we have some guidelines in place about what kinds of requests we will pursue.
Here are the guidelines for each of the different categories of projects:
- Plugin guidelines
- Example guidelines
- Codelab guidelines
But these aren't hard and fast rules. They're just meant to give you an idea of what we're looking for before you put time into building your feature request.
If you're unsure whether something fits, try posting it on our developer forums. And remember, even if your idea doesn't get accepted, we would still love for you to build it as a third party plugin or tutorial!
Your idea doesn't need to be 100% fleshed out with tinsel and diagrams before you go ahead and submit, but you should have a solid idea of what you're looking for. These are some good questions to ponder before you start to write:
- Why do I want this feature?
- Does this feature solve a problem?
- Who is the intended audience for this feature?
- Why does this feature serve them?
- What are some alternative options that could achieve the same thing?
Once you have those things figured out, you'll be most of the way to a good feature request!
You should now be ready to write your wonderful feature request. Make sure to fill out all the sections of the issue template, even the ones we didn't discuss here. As you do, remember to be concise!
Thank you for your interest in submitting a feature request, and happy issue writing!