Refactor templates

Closes GH-6.

Reviewed-by: Christian Murphy <[email protected]>
Reviewed-by: Remco Haszing <[email protected]>
Reviewed-by: Titus Wormer <[email protected]>

Author: wooorm

.github/ISSUE_TEMPLATE/1-bug.yml

@@ -6,6 +6,7 @@ body:
         * is this really a problem?
         * is this a problem here?
         * can this be solved in a different way?
+        * can this be contributed as a PR with a failing test instead?
     type: markdown
   - attributes:
       label: Initial checklist
@@ -16,82 +17,86 @@ body:
           required: true
         - label: I agree to follow the [code of conduct](https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md)
           required: true
-        - label: I searched [issues](https://github.com/search?q=user%3Asyntax-tree&type=Issues) and couldn’t find anything (or linked relevant results below)
+        - label: I searched [issues](https://github.com/search?q=user%3Asyntax-tree&type=issues) and [discussions](https://github.com/orgs/syntax-tree/discussions) and couldn’t find anything (or linked relevant results below)
           required: true
     id: initial-checklist
     type: checkboxes
   - attributes:
       description: |
-        Please test using the latest version of the relevant packages to make
-        sure your issue has not already been fixed.
-      label: Affected packages and versions
+        Which packages cause the bug?
+        Please test using latest versions.
+        Example: `[email protected]`.
+      label: Affected package
     id: affected-versions
     type: input
     validations:
       required: true
-  - attributes:
-      description: |
-        Link to repository or sandbox with runnable example of the issue.
-        Alternatively use the next section *Steps to reproduce*.
-      label: Link to runnable example
-    id: runnable-example
-    type: input
-    validations:
-      required: false
   - attributes:
       description: |
         How did this happen?
-        Please provide a [minimal and reproducible example](https://stackoverflow.com/help/minimal-reproducible-example).
+
+        Provide a [minimal and reproducible example](https://stackoverflow.com/help/minimal-reproducible-example).
+        Link to a repository or sandbox or show the code here.
+        Remove everything that is not needed.
+        Use plain Node and npm if possible.
       label: Steps to reproduce
     id: steps-to-reproduce
     type: textarea
     validations:
       required: true
   - attributes:
-      description: What should happen?
-      label: Expected behavior
-    id: expected-behavior
+      description: |
+        What happens?
+        What is wrong with the current behavior?
+      label: Actual behavior
+    id: actual-behavior
     type: textarea
     validations:
       required: true
   - attributes:
-      description: What happens instead?
-      label: Actual behavior
-    id: actual-behavior
+      description: |
+        What should happen instead?
+        Why should that happen?
+        Why is that better than the current behavior?
+      label: Expected behavior
+    id: expected-behavior
     type: textarea
     validations:
       required: true
   - attributes:
-      label: Affected runtime and version
+      label: Runtime
       description: |
-        What runtime are you using (such as `[email protected]` or `[email protected]`)?
-        Please test using the latest version.
+        What runtime are you using?
+        Please test using latest versions.
+        Example: `[email protected]` or `Chrome 131.0.6778.86`.
     id: runtime
     type: input
     validations:
-      required: true
+      required: false
   - attributes:
       description: |
-        What package manager are you using (such as `[email protected]`)?
-        Please test using the latest version.
-      label: Affected package manager and version
+        What package manager are you using?
+        Please test using latest versions.
+        Example: `[email protected]`.
+      label: Package manager
     id: package-manager
     type: input
     validations:
       required: false
   - attributes:
       description: |
-        What operating system are you using (such as `macOS Monterey 12.4`)?
-        Please test using the latest version.
-      label: Affected OS and version
+        What operating system are you using?
+        Please test using latest versions.
+        Example: `macOS Sequoia 15.1.1`.
+      label: Operating system
     id: operating-system
     type: input
     validations:
       required: false
   - attributes:
       description: |
         What tools are used to build or bundle the project?
-        Please test using the latest version.
+        Please test using latest versions.
       label: Build and bundle tools
       multiple: true
       options:
@@ -112,5 +117,5 @@ body:
     type: dropdown
     validations:
       required: false
-description: Describe a bug with a project
-name: 🐛 Bug report
+description: Report a bug
+name: 🐛 Bug

.github/ISSUE_TEMPLATE/2-feature.yml

@@ -15,34 +15,42 @@ body:
           required: true
         - label: I agree to follow the [code of conduct](https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md)
           required: true
-        - label: I searched [issues](https://github.com/search?q=user%3Asyntax-tree&type=Issues) and couldn’t find anything (or linked relevant results below)
+        - label: I searched [issues](https://github.com/search?q=user%3Asyntax-tree&type=issues) and [discussions](https://github.com/orgs/syntax-tree/discussions) and couldn’t find anything (or linked relevant results below)
           required: true
     id: initial-checklist
     type: checkboxes
   - attributes:
-      description: Please describe the problem you are trying to solve here.
+      description: |
+        Please describe the problem.
+
+        Forget about the particular solution you have in mind.
+        Solution time is later!
+
+        What is missing? What are the use cases?
+        Describe which use cases are important and which are nice to have.
+        Convince the maintainers that there is a real problem.
       label: Problem
     id: problem
     type: textarea
     validations:
       required: true
   - attributes:
       description: |
-        What should happen?
-        Please describe the desired behavior.
-      label: Solution
-    id: solution
+        Are there existing solutions?
+        Can these use cases be addressed already?
+      label: Current solutions
+    id: alternatives
     type: textarea
     validations:
       required: true
   - attributes:
       description: |
-        What are the alternative solutions?
-        Can this be solved in a different way?
-      label: Alternatives
-    id: alternatives
+        What is a better solution?
+        Why is that better than current solutions at addressing the use cases?
+      label: Proposed solutions
+    id: solution
     type: textarea
     validations:
       required: true
 description: Suggest an idea
-name: 🚀 Feature request
+name: 🚀 Feature

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: false
 contact_links:
   - about: Ask questions and discuss with other community members
-    name: 🙋 Ask a question
+    name: 💬 Discussions
     url: https://github.com/syntax-tree/unist/discussions

.github/pull-request-template.md

@@ -1,18 +1,23 @@
 <!--
   Please check the needed checkboxes ([ ] -> [x]).
-  Leave the comments as they are: they won’t show on GitHub.
-  We are excited about pull requests but please try to limit the scope,
+  Leave the comments as they are: they do not show on GitHub.
+
+  Please try to limit the scope,
   provide a general description of the changes,
   and remember it’s up to you to convince us to land it.
+
+  We are excited about pull requests.
+  Thank you!
 -->
 
 ### Initial checklist
 
 * [ ] I read the support docs <!-- https://github.com/syntax-tree/.github/blob/main/support.md -->
 * [ ] I read the contributing guide <!-- https://github.com/syntax-tree/.github/blob/main/contributing.md -->
 * [ ] I agree to follow the code of conduct <!-- https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md -->
-* [ ] I searched issues and couldn’t find anything (or linked relevant results below) <!-- https://github.com/search?q=user%3Asyntax-tree&type=Issues -->
-* [ ] I’ve added docs and tests or that’s not applicable
+* [ ] I searched issues and discussions and couldn’t find anything or linked relevant results below <!-- https://github.com/search?q=user%3Asyntax-tree&type=issues and https://github.com/orgs/syntax-tree/discussions -->
+* [ ] I made sure the docs are up to date
+* [ ] I included tests (or that’s not needed)
 
 ### Description of changes