Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

github: add troubleshooting steps to the issue template #350

Conversation

agilgur5
Copy link
Collaborator

@agilgur5 agilgur5 commented Jun 7, 2022

Summary

Add 3 very common troubleshooting steps to the issue template to help both users and maintainers/contributors

Details

  • these steps should help in 2 ways:

    1. hopefully avoid common misconfigurations from being repeatedly opened as bug reports
    • some of these have labels on them now to get a sense of how often they pop up
    1. help contributors and maintainers diagnose issues quicker as well as figure out if an issue is indeed a bug
    • the diagnosis questions are really common things we ask in an issue already, so think it would work out better to get that up-front
      • we have labels for some of these too
      • especially as issues can often get no response / go stale, and if it's truly a bug, it's better to know that earlier than later
  • condense the CONTRIBUTING.md a bit now that some of the most common debugging steps are in the issue template

    • didn't put in npm prune or clean: true yet, as don't want to make the issue template too big overnight
      • those also aren't as common an issue and people seem to figure out that an issue is due to caching bugs pretty often already

Next Steps

In somewhat of an order:

  • get a repro environment functioning and add it to the issue template repro question
  • probably want to move to GitHub's new beta Issue Forms moving forward, but thought it'd be best to get the details into Markdown first, then can migrate
    • and also creating Issue Forms seems to require moving to the multiple Issue Templates format where users select a "type" of issue (e.g. bug report vs. feature request etc), but we don't have multiple templates yet, so that could be confusing
  • write up a small PR template, basically the main sections I use in my PRs like everywhere ("Summary", "Details", and maybe some optional sections like this one)
  • write up a small feature request template (mentioned in Add schema checking for plugin options #312)

If needed, in the future we can add the npm prune, clean: true parts of the CONTRIBUTING.md to the troubleshooting steps. Similarly, we can ask if people have read the CONTRIBUTING.md as well if needed (in issue forms, that's a common checkbox and is an example in the docs). "Search terms" like the TypeScript repo has could be useful in the future as well and are gaining some traction in repos nowadays too.

- these steps should help in 2 ways:
  1. hopefully avoid common misconfigurations from being repeatedly
     opened as bug reports
    - some of these have labels on them now to get a sense of how often
      they pop up
  2. help contributors and maintainers diagnose issues quicker and
     figure out if an issue is indeed a bug
    - the diagnosis questions are really common things we ask in an
      issue already, so think it would work out better to get that
      up-front
      - we have labels for some of these too
      - especially as issues can often get no response / go stale, and
        if it's truly a bug, it's better to know that earlier than later

- condense the `CONTRIBUTING.md` a bit now that some of the most common
  debugging steps are in the issue template
  - didn't put in `npm prune` or `clean: true` _yet_, as don't want to
    make the issue template _too_ big overnight
    - those also aren't as common an issue and people seem to figure
      out that an issue is due to caching bugs pretty often already

- probably want to move to GitHub's new beta Issue Forms moving forward,
  but thought it'd be best to get the details into Markdown first,
  _then_ can migrate
  - and also creating Issue Forms seems to require moving to the
    multiple Issue Templates format where users select a "type" of issue
    (e.g. bug report vs. feature request etc), but we don't have
    multiple templates yet, so that could be confusing
@agilgur5 agilgur5 added the kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs label Jun 7, 2022
@ezolenko ezolenko merged commit a73e34e into ezolenko:master Jun 7, 2022
@agilgur5 agilgur5 added the scope: github GH-only changes, e.g. issue and PR templates, releases, etc (not docs or CI) label Jun 11, 2022
@agilgur5 agilgur5 deleted the github-add-troubleshooting-steps-to-template branch July 2, 2023 21:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: internal Changes only affect the internals, and _not_ the public API or external-facing docs scope: github GH-only changes, e.g. issue and PR templates, releases, etc (not docs or CI)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants