Create issue templates / forms

[mfisher87]

To help guide reporters to provide key information, we should have issue and PR templates or forms.

They can: Auto-label issues based on the chosen type; Direct users to other locations for certain types of issues, for example a "feature request" or "request for usage assistance" can be redirected to GitHub Discussions; direct users to input the needed information in a form-like workflow with checkboxes and markdown prompts; more?

[Sherwin-14]

Hey I think we need a bit more info here! Plus I think we should follow already existing template's like these one's.

[mfisher87]

I don't have really specific ideas, so I think you can explore on this a bit if you want! I think the approach we want is to use forms instead of a single template. Here's a project I did in the past that took this approach: https://github.com/nsidc/qgreenland/tree/main/.github/ISSUE_TEMPLATE

This way the user will be presented with a menu to help guide them to the right place when they click "new issue": https://github.com/nsidc/qgreenland/issues/new/choose

I think we should have "bug" as one workflow which auto-applies the "bug" label, and perhaps another "feature request" workflow which leads folks to GitHub Discussions. And then an "anything else" workflow that's more free-form. The bug workflow can provide forms which instruct the user to describe their issue clearly and provide a minimal reproducible example. I'm partial to sscce.org because it was the first I was exposed to, but any of the others would be fine. stack overflow's minimal reproducible example page is also good.

[mfisher87]

Thought of something: "What version of earthaccess do you have installed?" should be on the template/form, including a pip and conda command to answer that question.

[Sherwin-14]

@mfisher87 Hey I checked all the resources that you mentioned and I feel I'm up for it. The only issue is Yaml, how proficient should I be in yml to come up with this sort of a thing? Also the qgreenland one is awesome so should I just take all the elements from it and apply those to our context, or should we try something different maybe more unique to us?

[mfisher87]

I think if you use the QGreenland config as a starting place, you shouldn't need to be a YAML expert! YAML is tricky, though, so watch out for the gotchas, especially indentation, but since you're familiar with Python's significant indentation, I think that shouldn't be a challenge. I think if you use an editor that can highlight, should be OK!

Things I always try to remember: Data types can be surprising, so I always quote strings even though it's not required (e.g. no -> boolean false in YAML, but "no" -> string "no"); multi-line string behavior is confusing, as a rule of thumb use |- for multi-line strings containing Markdown like we would probably use in issue templates; use tools to validate like yamlfmt (we use this via pre-commit) or yq to validate syntax and parsing.

You could test the YAML out in your fork by merging it to the main branch or changing the default branch of your fork to the feature branch you're working in!

I think we probably want something more specialized to this project. My thoughts:

• We could at least take the "Bug" flow from QGreenland. We should clarify what we consider to be a bug, e.g. the behavior of the application differs from the documentation, the documentation contains errors, omissions from the documentation, other?
• Perhaps also a "community support" link which takes users to the Q&A page: https://github.com/nsidc/earthaccess/discussions/categories/q-a with some explanation of how this is different from a "bug", e.g. I am not sure if I'm doing things right, I need help understanding a feature, other?
• I think we want a "Suggest a new feature" flow that redirects users to GitHub discussions (specifically to create a new discussion in the "ideas" section: https://github.com/nsidc/earthaccess/discussions/new?category=ideas).

I think these docs will be valuable:

• https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms
• https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema

[Sherwin-14]

Thanks a lot for all this info! If I am not wrong we will have to come up 3 primary workflows one for bug , the other one for community support and the last one for suggesting a new feature?

[mfisher87]

Any time! Yeah, that's my initial thinking at least -- if you do set this up for testing on your fork, it'd be awesome if you could share a link in Slack to see if anyone wants to try it out and give feedback :)

Thanks for looking at this issue! 🙇

[Sherwin-14]

Hey can you assign me this one?

[mfisher87]

🚀 Thanks again :)

[Sherwin-14]

This is what I came up with https://github.com/Sherwin-14/earthaccess/issues/new/choose