Better bug report template

Some people create bug report issues on GitHub for their own bugs. Below is the current template text. It doesn’t explain that it’s for bugs in CPython itself, and only says to not create an issue if they’re not sure it’s a bug at all. I suggest:

  • Add a first sentence like “This is for bugs in CPython itself, not for bugs in user code.”.
  • Change “not sure whether what you’re experiencing is a bug” to “not sure whether what you’re experiencing is a bug in CPython”.
  • Add another option to the list: searching the problem with Google or Stack Overflow.

The current template:

  If you're new to Python and you're not sure whether what you're experiencing is a bug, the CPython issue tracker is not
  the right place to seek help. Consider the following options instead:

  - reading the Python tutorial:
  - posting in the "Users" category on
  - emailing the Python-list mailing list:
  - searching our issue tracker ( to see if
    your problem has already been reported

# Bug report

A clear and concise description of what the bug is.
Include a minimal, reproducible example (, if possible.

# Your environment

<!-- Include as many relevant details as possible about the environment you experienced the bug in -->

- CPython versions tested on:
- Operating system and architecture:

You can freely edit this text. Remove any lines you believe are unnecessary.

Sounds generally reasonable to me, FWIW. I would suggest going ahead with an issue documenting suggestions, or even directly with a pull request with your suggested changes.

I agree that the issue templates could be improved (FWIW, I was the initial author of them, and they haven’t changed much since). My main critique of the current templates is that they’re actually too long, though, which means that people end up not reading the whole thing.

I think:

  • The first sentence needs to be shorter, so that people get to the list of suggestions more quickly
  • We need to make it clearer that the list of suggestions is a list we expect users to have actively considered before filing the bug report, rather than a helpful list of suggestions that they’re free to skim over if they don’t feel like reading the whole thing. We could consider changing it to a checkbox-style thing (“I have tried googling this problem”; “I have tried searching the issue tracker for this problem”; etc)

Clarifying that it’s an issue tracker for CPython bugs (rather than bugs in user code) will probably also be worthwhile. Unfortunately, however, these bug reports are usually filed by beginners, who (believe it or not) may have difficulty understanding the difference between the two concepts. So whatever we do will be unlikely to fully solve the problem here.


I definitely agree with making them shorter if practicable; we’ve done something similar with the PEP PR templates recently. Also agreed with the practical difficulty of users understanding the difference between their Python code and CPython itself; we might want to briefly expand “CPython” to at least something like “the CPython interpreter itself”, which might help a little.

Of course, many newer users actually think they’ve found a bug with (C)Python rather than with their own code due to not understanding the reasons for a particular behavior, or making a mistake that they aren’t aware of, so even if they do fully read and understand the text they may still yet submit it.

I also note, too, that in order to get this far, the user must generally have already clicked through the issue chooser that gives them options to go to an external link to get Python help, so they may already be less likely to peruse those options to begin with vs. just ignoring it all. But it’s at least worth trying, I guess…

1 Like

You mean the “Getting help” here? That’s near the bottom of the list, maybe people just stop reading before they get there.