Skip to main content

Write a good issue

All great projects are built on user feedback. Blockly uses 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 addressed!

Got Questions?​

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.

Check for Duplicates​

Before you go about writing any type of issue, it is always good to see if a matching one already exists. Do some searches for duplicates or related issues:

If you find a matching issue, give it a thumbs up or add a comment detailing your thoughts. This is especially important for bug reports and feature requests. If developers see that an issue is getting a lot of attention, it is more likely to get worked on!

Types of issues​

There are three types of issues you can file in the Blockly repo:

  1. Bug reports
  2. Feature requests
  3. Documentation problems

Bug Reports​

Generally, the more information your bug has, the better. Here are a few things you might want to provide:

  • A Detailed Description of the buggy behavior is a great starting place. Be specific about when and where you're seeing the problem.
  • Screenshots, Gifs, or Screen Recordings 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.

Solidify your Reproduction​

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:

  1. Open X codelab.
  2. Go to Y page.
  3. Run Z example code.
  4. Observe the bad behavior, which looks like W.

If your issue is in Blockly core, try to reproduce it in the playground. Finally, if you think you know why the bug is happening, include that information as well. Again, be as specific as possible.

File a bug report

File your bug report in:

Feature Requests​

Is there something you want to change to make Blockly better? Do you have an idea for a plugin, example, or codelab? If so then you may want to create a feature request!

We would love to allow every 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 some of the different categories of projects:

  • Plugins
  • Examples: Show how to use only one or two Blockly features.
  • Codelabs: Show how to complete a single task or implement a single behaviour.

These aren't strict rules; they're meant to give you an idea of what we're looking for before you build 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!

Gather your Thoughts​

Your idea doesn't need to be 100% fleshed out with tinsel and diagrams before you 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, and how does this feature serve them?
  • What are some alternative options that could achieve the same thing?
File a feature request

File your feature request in:

Documentation problems​

Blockly has multiple sources of documentation, including:

We want our documentation to be clear, helpful, and complete.

If there's something incorrect or confusing in our documentation, please file a documentation problem to let us know. You can also file a documentation issue if there's a new piece of documentation that you'd like to see included. For instance, you could request a new codelab or a new page in the guides.

File a documentation problem

File any documentation issues in

What's Next?​

Thank you for helping improve Blockly! After you submit your issue:

  • The issue is automatically tagged with a status: triage label.
  • The Blockly team will take a look, and add other labels to categorize the issue.
  • We may ask follow-up questions and add a status: needs more info label to indicate that the issue needs more information before work can begin. If you don't provide more information in a timely manner, we may close your issue. If this happens, feel free to re-open it once you're able to provide the requested information.
  • Once the status: triage or status: needs more info labels are removed, you may start working on the issue if you'd like to. See the page on writing a good pull request for more information on submitting code to Blockly.