Issue and/or PR Templates

[CGBassPlayer]

Something I think would be useful for people users new to contributing to open source would be templates for creating issues and maybe PRs. I don't think it needs to be anything extravagant, but something to just let them know what they should put in when submitting an issue and possibly add some auto tagging.

Initial idea I am thinking is:

• Bug Report

  • What is the bug
  • What device (Phone, tablet, desktop, etc.)
  • Steps to reproduce
  • Screenshots

• Feature Request

  • Describe the feature
  • Is it related to a problem?
  • Did you see this feature somewhere else?

• Bug Fix PR

  • Issue(s) fixed
  • What was done to fix it?

Looking for suggestions of templates or things in templates as well

[elreydetoda]

(I've had a bunch of these links saved for a while as "advanced" templating solutions, so just going to drop all the links I have here and hopefully it'll help)

Awesome idea, I'd thought about it at one time but completely forgot to create an issue about it. Thank you! 🥳

While this probably isn't what we'd do, the @ansible-collections project has a bunch of files that we might be able to pull from: https://github.com/ansible-collections/.github

They also have all the other files we probably should have (i.e. SECURITY.md) and IIRC you can have multiple PR templates under the .github folder as well.

You can also link to different things if someone needs to submit feedback to a show, we could link them to the contact page: https://github.com/github/securitylab/blob/main/.github/ISSUE_TEMPLATE/config.yml

I think this one just had a really good design: https://github.com/linode/terraform-provider-linode/blob/main/.github/ISSUE_TEMPLATE/bug.yml

[CGBassPlayer]

These are great examples showing things I didn't even know about GitHub issue templates! I'll definitely be looking into this

[CGBassPlayer]

So I have been looking into this today and it seems like we can use yaml for issue templates, but as of right now, the pull request still used markdown templates as of right now.

I personally think this would work out the best for us because PRs should be a customizable compared to an issue which would being more like a form.

I made a mock up on a test repo and this is my initial idea of a bug report

The Device multi-select is Mobile, Tablet, and Desktop.
The Browser multi-select is FireFox, Chrome, Safari, and Microsoft Edge

And a basic feature request

[gerbrent]

This is so great both of you! I'll have a look aswell but see no reason why we can't implement some of these ideas.

My first hesitation with the amazing yaml example would be the downside of assigning rather rigid structure to our Issues when we've been using them in otherwise quite flexible ways - i.e. to track conversations and ideas that aren't strictly "bugs" or "feature requests". So, if there is a third option for flexibility that would be magnificent. Will check the repo and play a little, but on first blush this is fabulous! Thanks @CGBassPlayer ! 🎉

[CGBassPlayer]

...we've been using them in otherwise quite flexible ways - i.e. to track conversations and ideas that aren't strictly "bugs" or "feature requests". So, if there is a third option for flexibility that would be magnificent...

Well you are in luck @gerbrent! There is an option to create a blank issue at the bottom that will take you right to the usual new issue page.

I see these templates more as way to help new people figure out what they should put in a bug report or feature request rather than a strict structure we would have to stick to. I am also going to see if I can cheat a little bit and make a blank issue template if you think the blank issue could use more prominence in the issue type selection.

One thing I did notice with these new issue templates is that they are not yet implemented on the GitHub app, so those users will still also get a blank issue when they create one as well.

[gerbrent]

this is so great!

[elreydetoda]

@CGBassPlayer , this is looking amazing! Thank you for taking the time to do all this!

I didn't even know about GitHub issue templates! 

I know, I was the same way and when I noticed them when filing bug reports I saved them in my notion notes. That way when I wanted to I could come back and use them (like now 😁).

initial idea of a bug report

So far I think this looks awesome. I would consider swapping the textarea for a markdown. That way it should still let them upload pictures and other things to help convey what's going on 😁

Also, we might want to include check boxes for making sure people have read the different docs (contributors.md, code if conduct (if/when we get one, but can be commented out for now), etc...) similar to GH's example of the Code of conduct: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema#about-githubs-form-schema

- type: checkboxes attributes:
  label: Code of Conduct
  description: The Code of Conduct helps create a safe space for everyone. We require that everyone agrees to it. 
  options:
    - label: I agree to follow this project's [Code of Conduct](link/to/coc)
  required: true 

One thing I did notice with these new issue templates is that they are not yet implemented on the GitHub app, so those users will still also get a blank issue when they create one as well.

There's not much we can do about this... I've seen similar issues with other thing on the GH app. So, we'll have to wait for them to support it better.

[CGBassPlayer]

@elreydetoda markdown is only text rendered while filling out the form for giving instructions, thanks, or anything you need to convey that doesn't need to be read on the ticket after. When you use the textarea, it works just like a markdown area in a blank issue. You can upload images, make lists, and do all the other markdown things.

[elreydetoda]

Ah, gotcha. Just from your screenshot it looks like there isn't the normal context menu (bold, italicized, etc.) that might be helpful for people who are new to markdown.

Thanks for letting me know though @CGBassPlayer 😁

[CGBassPlayer]

No problem! I thought the same thing at first as well. But once you click into it, you get the normal markdown view

[CGBassPlayer]

So I am adding the the contributing checkbox for the templates. Is there any specific wording we want for this?

Also, do you guys think it would be good to have a development related template? Maybe to list the tools they are having an issue with and a normal summary to describe it? Kind of like this (most of this text is just stand in)

[gerbrent]

yes, that looks helpful!

I'm gonna wager Docker gets submitted first ; )

[gerbrent]

for specific wording: insert what you feel and we can always redact later..

[CGBassPlayer]

Is there any other ideas for templates we want before I mark this PR as ready?

[gerbrent]

I wonder if a "Episode metadata has errors" template might be helpful?
To cover the case where a listener notices a dead link, a typo, or incorrectly tagged guest, etc. for a specific episode.

[CGBassPlayer]

I like the idea. I can throw the show notes tag on those so we know it has to do with dead links. I'll add that now

[gerbrent]

Example of an issue reported via these new (wonderful) templates:

#430

There are two small issues I would like us to investigate:

1. An image was added to the Summary section and notice the LARGE gap of content before the end of the template.

2. the "I have read through the Contributing Guidelines" section necessarily gets a check mark on every issue template submitted, however in the Issue post-submission, this is then "tracked" as a task. So, then, every single issue submitted will have a tracked, completed task associated with it.

[CGBassPlayer]

I can look into this. I am not sure why there was a large gap. Very strange to me.

But I can see how the checkbox being a task can get annoying. Did we want to remove it or try changing to something else?

[gerbrent]

On the submitted issue:

---

On the issue template:

Notice there are THREE lines that suggest reading the Contributing Guidelines. Maybe a little superfluous...

[CGBassPlayer]

@gerbrent do you want the Contributing check removed completely? The bottom link will always be put there by GitHub so we don't necessarily need to put our own in the issue forms if we don't want it.

Also. It seems that the screenshot has a large transparent section on the right and underneath it.

All the white section when I try to save the image is transparent on GitHub and is what is causing the large space. Could it be the screenshot method? Or did GitHub somehow add it after it being uploaded? More testing is going to be needed for this.

[gerbrent]

will test that! nice catch..

[CGBassPlayer]

@gerbrent

Notice there are THREE lines that suggest reading the Contributing Guidelines. Maybe a little superfluous...

the "I have read through the Contributing Guidelines" section necessarily gets a check mark on every issue template submitted, however in the Issue post-submission, this is then "tracked" as a task. So, then, every single issue submitted will have a tracked, completed task associated with it.

Based on your concerns, are you thinking we should remove the contributing checkbox from the issue forms? We can put some text in that is only rendered while filling out the issue for them to review it.