I'd clarify that this isn't for reporting bugs in Python, but that it's for bugs in documents. But yeah, I think this would be an improvement.

Would some headings help? (This is for code, but for example.)

On that .github/ISSUE_TEMPLATE.md example, I see GitHub now tells me:

You are using an old version of issue templates. Please update to the new issue template workflow. Learn more

So shall we use the new .github/ISSUE_TEMPLATE/config.yml version?

So shall we use the new .github/ISSUE_TEMPLATE/config.yml version?

@hugovk To my mind, it seems overkill for bugs in documentation. I assume that people reporting bugs here are experienced developers (if they follow the PEP1 process, i.e. they report only bugs), and they don't need such issue forms. What's your opinion on that?

But if there's a consensus, I can update the template to use the yaml file.

I assume that people reporting bugs here are experienced developers (if they follow the PEP1 process, i.e. they report only bugs),

A lot of them aren't, and many are experienced developers and still might gloss over the issue template. The main goal isn't to give contributors more boilerplate text to read, edit and delete (or ignore), which the Contributing Guide and PEP 1 (especially with #2378 ) already cover. Rather, it should be to provide clear, hard to miss, easy to use and actionable pre-triage, so they can understand at a glance whether their issue is appropriate here, and if not, where to take it—which is what the template chooser does.

and they don't need such issue forms.

I've not used the new format yet. If it's only for forms, sure, this one is simple enough :)

Actually, no, the config.yaml isn't the configuration for the issue creation forms, which I don't think we need here, its for the far more useful (at least in this case) template chooser. See, for example, Numpy's; we wouldn't need that many options, but it gives you an example of what it looks like and what can be done with it.

In summary, it gives users a set of short, simple and actionable options (that we configure) when clicking the New Issue button, which can be to one or more issue templates (or even just a blank issue), or to external sites (Python-Ideas, Discourse, BPO, etc), rather than dumping them straight to a raw issue with a bunch of pre-filled plain-text boilerplate. This is way friendlier and more effective, especially for what we're trying to do (redirect users with issues that don't belong here to better places) versus just a generic issue template, because it actually makes sure users read them and affirmatively choose one, while keeping them short and very quick to navigate.

I'd also suggest waiting just a bit until #2378 is merged (which maybe we can go ahead and do now, since every active PEP editor has now approved it and the last comments were addressed), since that changes and improves the existing text and provides new/updated sections that we can link to directly in PEP 1 and the contributing guide.

I am not enthusiastic about this change. Inappropriate issues are rare and easily dealt with, and the proposed templates add more overhead for us maintainers to deal with and more boilerplate for new contributors to read.

I'd suggest just ditching the template and adding the recommended an issue chooser instead, with one button to just open a blank issue with a line of text explaining what issues here are for (or perhaps one for PEP text issues and one for website issues, with perhaps a link of text each), and maybe a couple other options with links to other places, e.g. "Report a bug in Python" -> BPO/GH, "Propose a new idea" -> Python-Ideas/Discourse Ideas, etc.

This is fairly simple for us to maintain, minimizes the text new users need to read to the most important few lines while ensuring they read it, and allows experienced users to go right to an issue with one click and no boilerplate.

@vpoulailleau Would you like to make a fresh PR following CAM's suggestion?

For reference, the CPython repo just added something a bit like this

• https://github.com/python/cpython/issues/new/choose
• Add minimal issue templates cpython#91569

Thanks!

@hugovk @CAM-Gerlach OK, I'll do this this week.