From fb172dc4e6a51206c3001aef772822daac012881 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= <slorber@users.noreply.github.com>
Date: Thu, 17 Jun 2021 12:04:31 +0200
Subject: [PATCH] misc: more issue template improvements (#4994)

---
 .github/ISSUE_TEMPLATE/bug.md      | 21 ++++++++-----
 .github/ISSUE_TEMPLATE/config.yml  |  3 ++
 .github/ISSUE_TEMPLATE/feature.md  | 49 +++++++++++++++++++++---------
 .github/ISSUE_TEMPLATE/proposal.md |  4 +--
 4 files changed, 54 insertions(+), 23 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
index e195e35c4d..8540cb7baf 100644
--- a/.github/ISSUE_TEMPLATE/bug.md
+++ b/.github/ISSUE_TEMPLATE/bug.md
@@ -8,6 +8,9 @@ labels: 'bug, needs triage'
 
   ! PLEASE HELP US HELP YOU !
 
+  Make it obvious to understand and reproduce this bug.
+  Ideally, we should be able to understand it without running any code.
+
   Bugs are fixed faster if you include:
   - a repro repository to inspect the code
   - an url to see the problem live (if possible)
@@ -29,6 +32,8 @@ This way we know you've done these steps first.
 - [ ] I'm using the latest version of Docusaurus.
 - [ ] I have tried the `npm run clear` or `yarn clear` command.
 - [ ] I have tried `rm -rf node_modules yarn.lock package-lock.json` and re-installing packages.
+- [ ] I have tried creating a repro with https://new.docusaurus.io
+- [ ] I have read the console error message carefully (if applicable)
 
 ### Description
 
@@ -38,9 +43,9 @@ This way we know you've done these steps first.
 
 (Write your answer here.)
 
-## To Reproduce
+## Steps to reproduce
 
-If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.
+Use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.
 
 (Write your steps here:)
 
@@ -58,18 +63,20 @@ If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible
 
 (Write what you thought would happen.)
 
-## Actual Behavior
+## Actual behavior
 
 <!--
   Did something go wrong?
   Is something broken, or not behaving as you expected?
   Describe this section in detail, and attach screenshots if possible.
   Don't only say "it doesn't work"!
+  Please submit exhaustive and complete log messages (we also need the error strack-traces, not just the message).
+  Please read error messages carefully: it often tells you exactly what you are doing wrong
 -->
 
-(Write what happened. Add screenshots, if applicable.)
+(Write what happened. Add full console log messages and screenshots, if applicable.)
 
-## Your Environment
+## Your environment
 
 <!-- Include as many relevant details about the environment you experienced the bug in -->
 
@@ -79,9 +86,9 @@ If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible
 - Environment name and version (e.g. Chrome 78.0.3904.108, Node.js 10.17.0):
 - Operating system and version (e.g. Ubuntu 20.04.2 LTS):
 
-## Reproducible Demo
+## Reproducible demo
 
-If possible, use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.
+Use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.
 
 (Paste the link to an example repo, including a `docusaurus.config.js`, and exact instructions to reproduce the issue.)
 
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 8cfe1b1ce4..366d41a1aa 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: 🚀 Feature request
+    url: https://docusaurus.io/feedback/
+    about: The Canny board to send us feature requests, vote and measure the interest of users. Useful to submit a featurre request when you have an idea but no concrete api design proposal.
   - name: ❓ Simple question - Discord chat
     url: https://discord.gg/docusaurus
     about: This issue tracker is not for technical support. Please use our Discord chat, and ask the community for help.
diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md
index fe752f3b2e..bc46857041 100644
--- a/.github/ISSUE_TEMPLATE/feature.md
+++ b/.github/ISSUE_TEMPLATE/feature.md
@@ -1,12 +1,14 @@
 ---
-name: 🚀 Feature
-about: Submit a proposal/request for a new feature
+name: 💅 Feature design / RFC
+about: Submit a detailed feature request with a concrete proposal, including an exhaustive API / UI design
 labels: 'feature, needs triage'
 ---
 
 <!--
-  Consider requesting the feature on https://docusaurus-2.netlify.com/feedback/ instead.
-  Feature requests on v1 are more likely to be missed as we're focusing on building v2.
+  IMPORTANT:
+  - We expect you to submit a feature request including a real design (API / UI...), not just a basic idea
+  - The design does not have to be perfect, we'll discuss it and fix it if needed
+  - For a more "casual" feature requests, consider using Canny instead: https://docusaurus.io/feedback
 -->
 
 ## 🚀 Feature
@@ -17,20 +19,39 @@ labels: 'feature, needs triage'
 
 (Write your answer here.)
 
+### Has this been requested on [Canny](https://docusaurus.io/feedback)?
+
+(Please post the Canny link, it is helpful to see how much interest there is for this feature)
+
 ## Motivation
 
-(Please outline the motivation for the proposal.)
+(Please outline the motivation for the proposal and why it should be implemented. Has this been requested by a lot of users on our )
 
-## Pitch
+## API Design
 
-(Please explain why this feature should be implemented and how it would be used.)
+(Please describe how Docusaurus users will enable and configure this feature, and what it will look like)
 
 <!--
-  What happens if you skip this step?
-
-  Someone will read your feature proposal and maybe will be able to help you,
-  but it’s unlikely that it will get much attention from the team. Eventually,
-  the issue will likely get closed in favor of issues that have better explanations
-
-  Thanks for helping us help you!
+  Please explain in an exhaustive way what are the config/plugin options and their respective effects.
+  For visual elements, please send us some screenshots/mockups of what it should look like. You can use https://excalidraw.com to create simple mockups.
+-->
+
+<!--
+  What happens if you skip this step? This issue will be automatically closed.
+  Your feature request is just an idea for now, please use Canny for that: https://docusaurus.io/feedback
+-->
+
+## Have you tried building it?
+
+(Please explain how you tried to build the feature by yourself, and how successful it was)
+
+<!--
+  Docusaurus 2 has a plugin system and theming support.
+  Quite often, this gives you the opportunity to build the feature you need by yourself.
+
+  We expect you to put your own work in this feature, particularly if it is not requested by a lot of users.
+  If we see it in action on your own site, it is easier to understand its value, and how it should work.
+
+  If you can't build it yourself for technical reasons, please explain why.
+  We are willing to help you, and eventually providing new APIs to make it possible.
 -->
diff --git a/.github/ISSUE_TEMPLATE/proposal.md b/.github/ISSUE_TEMPLATE/proposal.md
index 83c1ae9cb1..2ab2edb128 100644
--- a/.github/ISSUE_TEMPLATE/proposal.md
+++ b/.github/ISSUE_TEMPLATE/proposal.md
@@ -5,8 +5,8 @@ labels: 'proposal, needs triage'
 ---
 
 <!--
-  Consider requesting the feature on https://docusaurus-2.netlify.com/feedback/ instead.
-  Feature requests on v1 are more likely to be missed as we're focusing on building v2.
+  This is not for feature requests.
+  Consider requesting the feature on https://docusaurus.io/feedback instead.
 -->
 
 ## 💥 Proposal