github: Switch to yaml issue templates #27025

willcl-ark commented at 11:49 AM on February 2, 2023: contributor

The new YAML templates provide more flexibility and can be designed to extract more information from users when submitting issues, avoiding initial back-and-forth when reports do not include enough background information to begin with.

Key differences:

YAML format
Allows us to require responses to certain questions
Not currently compatible with GitLab (.md only)

This does keep the "Blank Issue" option at the bottom.

Testing this must be done with the master branch of the repo, which is slightly annoying for this repo. I have therefore pushed this to my own fork so that you can see the new templates, along with how the output is rendered in newly-created issues:

github.com/willcl-ark/bitcoin/issues

I did make some minor changes to some of the template wording, but this change could also be a good time to add/remove additional questions.

This seems like a net-positive for me, setting aside the issue that if we ever migrated away from GitHub these might have to be ported back to *.md (or something else), but that seems easy-enough that this change would be worth it.

Curious to know what others think of this, and whether they would suggest adding any other questions to any of the templates as part of this update?

DrahtBot commented at 11:49 AM on February 2, 2023: contributor

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

Reviews

See the guideline for information on the review process.

Type	Reviewers
ACK	achow101, glozow
Concept ACK	fanquake, pinheadmz, kouloumos, hebasto

If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

willcl-ark force-pushed on Feb 2, 2023

fanquake commented at 12:10 PM on February 2, 2023: member

Concept ACK

willcl-ark force-pushed on Feb 2, 2023

in .github/ISSUE_TEMPLATE/config.yaml:4 in b1f20ba1ed outdated

   0 | @@ -0,0 +1,7 @@
   1 | +blank_issues_enabled: true
   2 | +contact_links:
   3 | +  - name: Bitcoin Core Developers
   4 | +    url: "https:bitcoincore.org"

flack commented at 10:14 AM on February 3, 2023:

Shouldn't this be https://bitcoincore.org?

willcl-ark commented at 10:15 AM on February 3, 2023:

Yep!

willcl-ark commented at 1:28 PM on February 3, 2023:

Fixed in 6d67ee23dbbe007a910e7cebb0d3ee4d1268ca15

willcl-ark commented at 1:35 PM on February 3, 2023:

Commit is now b18032cfa6ee590f231448e67e05c862750ea61f since I fixed the config.yaml not being detected (must be config.yml)

willcl-ark force-pushed on Feb 3, 2023

fanquake commented at 3:49 PM on February 8, 2023: member

What are the next steps here? Undraft?

pinheadmz commented at 7:07 PM on February 8, 2023: member

concept ACK

great work! I can't think of anything to add or change

willcl-ark marked this as ready for review on Feb 8, 2023

willcl-ark commented at 7:47 PM on February 8, 2023: contributor

I suppose one other question is whether having more/mandatory questions will put people off submitting issues, although as mentioned in OP there is still the "blank issue" option available (in small writing) at the bottom of the issues page...

in .github/ISSUE_TEMPLATE/bug.yml:90 in b18032cfa6 outdated

  85 | +      label: Machine specifications
  86 | +      description: |
  87 | +        What are the specifications of the host machine?
  88 | +        e.g. OS/CPU and disk type, network connectivity
  89 | +    validations:
  90 | +      required: true

flack commented at 7:56 PM on February 8, 2023:

If you want to reduce the number of required fields, this might be a good candidate to make optional, since I guess there are quite a few issues that are not related to hardware (also, OS in the description is a bit redundant, since this is already asked in the question above)

flack commented at 7:57 PM on February 8, 2023:

P.S.: Also, if you want the user to seriously describe CPU, disk, network and so on, textarea might be better than single line

willcl-ark commented at 8:11 PM on February 20, 2023:

Updated as a textarea in 5527f7490

fanquake commented at 5:56 PM on February 20, 2023: member

I suppose one other question is whether having more/mandatory questions will put people off submitting issues,

If people can't be bothered to supply what we think is the minimum required information, then we will likely be unable to debug anything anyways. However, sometimes (fixable/informative) issues do come in the form of a randonly pasted debug log or similar. So if there is still an option for someone to dump something, I think this is ok. @achow101 @glozow @MarcoFalke @hebasto any thoughts here?

willcl-ark commented at 8:07 PM on February 20, 2023: contributor

So if there is still an option for someone to dump something, I think this is ok.

It would also be possible to add a new BLANK issue template so that the blank issue template gets a big green button like the others (rather than needing to click the small hyperlink at the bottom), but IMO this would slightly defeat the point of requiring more info.

willcl-ark force-pushed on Feb 20, 2023

in .github/ISSUE_TEMPLATE/config.yml:5 in 5527f74901 outdated

   0 | @@ -0,0 +1,8 @@
   1 | +blank_issues_enabled: true
   2 | +contact_links:
   3 | +  - name: Bitcoin Core Security Policy
   4 | +    url: https://github.com/bitcoin/bitcoin/blob/master/SECURITY.md
   5 | +    about: View security policy

achow101 commented at 11:30 PM on February 20, 2023:

There's already a big green button for the security policy, so I don't think we need to add a second one manually.

willcl-ark commented at 11:30 AM on February 21, 2023:

This config option enables the Bitcoin Core Security Policy row with the Open button which links to our SECURITY.md. The Report a security vulnerability row, with the big green Report a vulnerability button seems to be a GitHub default (which I don't know how to disable).

My preference would be to keep both, as otherwise the link to SECURITY.md via the Report a vulnerability button is from a small right menu item:

achow101 commented at 5:02 PM on February 21, 2023:

It looks like it's different depending on your repo permissions.

For me, the big green button says "View Policy" and clicking on it goes to https://github.com/willcl-ark/bitcoin/security/policy. For a repo I own/admin/maintain, it shows the page similar to the one in your screenshot.

maflcko commented at 10:49 AM on March 10, 2023:

Looks like this wasn't addressed?

willcl-ark commented at 11:42 AM on March 10, 2023:

Hmmm, for me as a non admin this repo now looks like:

The green View Policy button takes me to a page which includes "Policy" and "Advisories", defaulting to showing the security policy SECURITY.md.

The row below that, "Bitcoin Core Security Policy" with the non-green Open button links me straight to SECURITY.md, which I agree is in theory somewhat redundant. If there is a preference to remove the second row, "Bitcoin Core Security Policy" direct link, then we could do that?

maflcko commented at 12:24 PM on March 22, 2023:

If there is a duplicate entry, at least it could be moved to the first position, as some people seem to miss it?

willcl-ark commented at 1:40 PM on March 22, 2023:

@MarcoFalke so it seems that it is not possible to move this particular entry (nor the bottom two) to the top... Apparently we can re-order our custom templates by changing the filenames to 01_xxx, 02_xxx etc., but the two bottom entries, and the security report are just part of the GitHub UI :(

There is a GitHub beta setting to enable the Report a Vulnerability big green button for all users (changing it from a duplicate View Policy big green button), as I've done now for my fork, and can be seen below:

But I don't think this is what we want as I think it will subvert the security@bitcoincore.org email that we want...

in .github/ISSUE_TEMPLATE/bug.yml:53 in 5527f74901 outdated

  48 | +    attributes:
  49 | +      label: Relevant log output
  50 | +      description: |
  51 | +        Please copy and paste any relevant log output. This is normally the contents of a `debug.log` or `config.log` file.
  52 | +        This will be automatically formatted into code, so no need for backticks. If longer than 10,000 chars use a pastebin type site and just leave a link.
  53 | +      render: shell

achow101 commented at 11:43 PM on February 20, 2023:

The docs say that users can upload files as long as render is not set. I think it would be better to let reporters upload their log files rather than requiring them to use a paste site.

kouloumos commented at 9:20 AM on February 21, 2023:

This could also help to avoid scenarios where thousands of lines of pasted logs make the issue harder to read.

willcl-ark commented at 11:37 AM on February 21, 2023:

I made this change in 3fa1185dd. Seems like files can be added to the textarea with drag & drop

achow101 commented at 11:43 PM on February 20, 2023: member

Concept ACK

It would also be possible to add a new BLANK issue template so that the blank issue template gets a big green button like the others (rather than needing to click the small hyperlink at the bottom), but IMO this would slightly defeat the point of requiring more info.

I think the link at the bottom is fine. The people who would use it can probably figure it out.

in .github/ISSUE_TEMPLATE/bug.yml:52 in 5527f74901 outdated

  47 | +    id: logs
  48 | +    attributes:
  49 | +      label: Relevant log output
  50 | +      description: |
  51 | +        Please copy and paste any relevant log output. This is normally the contents of a `debug.log` or `config.log` file.
  52 | +        This will be automatically formatted into code, so no need for backticks. If longer than 10,000 chars use a pastebin type site and just leave a link.

kouloumos commented at 9:10 AM on February 21, 2023:

I think that a good addition here could be some of the usual hints posted in bug investigation comments such as #27134 (comment), which are:

You can find the debug.log in your data dir. Please be aware that the debug log might contain personally identifying information.

willcl-ark commented at 11:36 AM on February 21, 2023:

Added in 3fa1185dd

kouloumos commented at 9:15 AM on February 21, 2023: contributor

Concept ACK

in .github/ISSUE_TEMPLATE/bug.yml:90 in 5527f74901 outdated

  85 | +      label: Machine specifications
  86 | +      description: |
  87 | +        What are the specifications of the host machine?
  88 | +        e.g. OS/CPU and disk type, network connectivity
  89 | +    validations:
  90 | +      required: true

glozow commented at 10:01 AM on February 21, 2023:

Agree this could be an optional "additional info about env or machine" as it could be irrelevant to the issue / confusing. (feel free to ignore as this is just me bikeshedding)

willcl-ark commented at 11:36 AM on February 21, 2023:

I agree that this is nice-to-have rather than essential (for most bug reports) and so made it optional in 3fa1185dd

glozow commented at 10:02 AM on February 21, 2023: member

Concept ACK, I think this is an improvement and have no major issues with it.

github: Switch to yaml issue templates

These provide more flexibility and can be designed to extract more
information from users when submitting issues.

3fa1185dda

willcl-ark force-pushed on Feb 21, 2023

willcl-ark commented at 11:38 AM on February 21, 2023: contributor

Thanks for the comments. I have incorporated the changes into 3fa1185dd which is also live on my fork.

hebasto commented at 12:43 PM on February 21, 2023: member

Concept ACK.

achow101 commented at 4:36 PM on March 9, 2023: member

ACK 3fa1185dda3b000b9c3956422fd2351e40969dec

glozow commented at 5:06 PM on March 9, 2023: member

ACK 3fa1185dda3b000b9c3956422fd2351e40969dec

glozow merged this on Mar 9, 2023

glozow closed this on Mar 9, 2023

sidhujag referenced this in commit 36b6f5a5e2 on Mar 9, 2023

sidhujag referenced this in commit a114f7ba75 on Mar 10, 2023

bitcoin locked this on Mar 21, 2024