Issues

Issues on open source projects should be clear and concise.

How To Ask a Good Question[2]

Search, and research

...and keep track of what you find. Even if you don't find a useful answer elsewhere on the site, including links to related questions that haven't helped can help others in understanding how your question is different from the rest.

Write a title that summarizes the specific problem

The title is the first thing potential answerers will see, and if your title isn't interesting, they won't read the rest. So make it count:

Examples:

Introduce the problem before you post any code

In the body of your question, start by expanding on the summary you put in the title. Explain how you encountered the problem you're trying to solve, and any difficulties that have prevented you from solving it yourself. The first paragraph in your question is the second thing most readers will see, so make it as engaging and informative as possible.

Help others reproduce the problem

Not all questions benefit from including code, but if your problem is with code you've written, you should include some. But don't just copy in your entire program! Not only is this likely to get you in trouble if you're posting your employer's code, it likely includes a lot of irrelevant details that readers will need to ignore when trying to reproduce the problem. Here are some guidelines:

Include all relevant tags

Try to include a tag for the language, library, and specific API your question relates to. If you start typing in the tags field, the system will suggest tags that match what you've typed - be sure and read the descriptions given for them to make sure they're relevant to the question you're asking! See also: What are tags, and how should I use them?

Proof-read before posting!

Now that you're ready to ask your question, take a deep breath and read through it from start to finish. Pretend you're seeing it for the first time: does it make sense? Try reproducing the problem yourself, in a fresh environment and make sure you can do so using only the information included in your question. Add any details you missed and read through it again. Now is a good time to make sure that your title still describes the problem!

Post the question and respond to feedback

After you post, leave the question open in your browser for a bit, and see if anyone comments. If you missed an obvious piece of information, be ready to respond by editing your question to include it. If someone posts an answer, be ready to try it out and provide feedback!

Look for help asking for help

In spite of all your efforts, you may find your questions poorly-received. Don't despair! Learning to ask a good question is a worthy pursuit, and not one you'll master overnight. Here are some additional resources that you may find useful:

Example Issue Format[1]

Describe the bug

Include a clear and concise description of what the problem is, including what you expected to happen, and what actually happened.

Steps to reproduce the bug

It's important that we are able to reproduce the problem that you are experiencing. Please provide all code and relevant steps to reproduce the problem, including your BUILD/CMakeLists.txt file and build commands. Links to a GitHub branch or godbolt.org that demonstrate the problem are also helpful.

Does the bug persist in the most recent commit?

We recommend using the latest commit in the master branch in your projects.

What operating system and version are you using?

If you are using a Linux distribution please include the name and version of the distribution as well.

What compiler and version are you using?

Please include the output of gcc -v or clang -v, or the equivalent for your compiler.

What build system are you using?

Please include the output of bazel --version or cmake --version, or the equivalent for your build system.

Additional context

Add any other context about the problem here.

References

  1. https://github.com/google/googletest/issues/new?assignees=&labels=bug&template=00-bug_report.md&title=
  2. https://stackoverflow.com/help/how-to-ask

Last modified: 202201121317