From becff410ad392303553a26fc09cf1471dc829829 Mon Sep 17 00:00:00 2001
From: Anton Gilgur <agilgur5@gmail.com>
Date: Mon, 6 Jun 2022 20:31:22 -0400
Subject: [PATCH] github: add troubleshooting steps to the issue template

- 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
---
 .github/issue_template.md | 37 ++++++++++++++++++++++++++++++++-----
 CONTRIBUTING.md           | 13 +++++++------
 2 files changed, 39 insertions(+), 11 deletions(-)

diff --git a/.github/issue_template.md b/.github/issue_template.md
index 6660110d..5bab9686 100644
--- a/.github/issue_template.md
+++ b/.github/issue_template.md
@@ -1,11 +1,38 @@
-#### What happens and why it is wrong
-
-#### Environment
+## Troubleshooting
+<!--
+  Please follow the steps below to ensure that you have troubleshot this problem sufficiently to believe that it is a bug in this plugin.
+  Many issues are the result of common misconfigurations and are not bugs, so please follow the steps to help us help you and prioritize limited volunteer maintainer time.
+-->
 
-<!--- describe your environment if it is relevant to the problem --->
+1. Does `tsc` have the same output? If so, please explain why this is incorrect behavior
+    <!--
+      This plugin uses the TS LanguageService under-the-hood.
+      It tries to mimic tsc and add Rollup semantics where possible, so if tsc has the same output, the error you're getting may be correct and accurate.
+      There are cases where they should differ, however, so if this is one of those, please elaborate.
+    -->
+
+1. Does your Rollup plugin order match [this plugin's compatibility](https://github.com/ezolenko/rollup-plugin-typescript2#compatibility)? If not, please elaborate
+    <!--
+      Rollup plugin order matters, so if there is a mismatch here, that could be the cause of your issue.
+    -->
+
+1. Can you create a [minimal example](https://stackoverflow.com/help/minimal-reproducible-example) that reproduces this behavior?
+    <!--
+      Minimal reproductions help us find the root cause of an issue much more expediently than trying to interpret and disentangle a complicated repo.
+      The process of creating a minimal reproduction also often helps users find a misconfiguration in their code.
+      It could also help you identify the root cause yourself and potentially create a Pull Request to fix it!
+    -->
+
+## What happens and why it is incorrect
+<!--
+  Please explain the issue you are encountering and why you believe it is incorrect behavior, in detail.
+  Please list any error messages here.
+-->
 
-##### Versions
+## Environment
+<!-- Please describe your environment, especially anything potentially relevant to the problem -->
 
+### Versions
 <!--
   PLEASE RUN THIS COMMAND INSIDE YOUR PROJECT:
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 06f7db3b..0a061ff8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,15 +4,16 @@
 
 Report any bugs [in the GitHub Issue Tracker](https://github.com/ezolenko/rollup-plugin-typescript2/issues).
 
-Attach your `tsconfig.json`, `package.json` (for versions of dependencies), `rollup.config.js`, and anything else that could influence module resolution, ambient types, and TS compilation.
+Please follow the issue template as closely as possible:
 
-Check if the problem is reproducible after running `npm prune` to clear any rogue types from `node_modules` (by default TS grabs _all_ ambient types).
+- Attach your `tsconfig.json`, `package.json` (for versions of dependencies), `rollup.config.js`, and any other pieces of your environment that could influence module resolution, ambient types, and TS compilation.
 
-Check if you get the same problem with `clean` option set to `true` (might indicate a bug in the cache).
+Some additional debugging steps you can take to help diagnose the issue:
 
-If it makes sense, check if running `tsc` directly produces similar results.
-
-Attach plugin output with `verbosity` option set to 3 (this will list all files being transpiled and their imports).
+- Attach plugin output with `verbosity` option set to `3` (this will list all files being transpiled and their imports).
+- If it makes sense, check if running `tsc` directly produces similar results.
+- Check if you get the same problem with `clean` option set to `true` (might indicate a bug in the cache).
+- Check if the problem is reproducible after running `npm prune` to clear any rogue types from `node_modules` (by default TS grabs _all_ ambient types).
 
 ## Developing