From 3034709df07d98fc35c01f37ab7bb09e6399d4e5 Mon Sep 17 00:00:00 2001
From: Dag Wieers <dag@wieers.com>
Date: Tue, 4 Sep 2018 17:31:45 +0200
Subject: [PATCH] Improve GitHub templates (#44455)

* Improve GitHub templates

The existing templates are basically a copy for each type of issue (bug,
feature, doc) whereas we can make the template more specific to the task
at hand.

This PR includes:
- More specific sections depending on the type of issue
- More concise and direct instructions (NO NEED FOR FRUSTRATION CAPS!)
- Single-line comments (no need to guide people to avoid wrong edits)
- Improved paste area
- Better headings/titles
- No 'Summary' title for PRs (so commit information is placed correctly)

This PR would require some improvements to Ansibot.

* Remove controversial Ansibot stuff

Make it easier to get the first batch merged.

* Restore ISSUE_TEMPLATE.md

* Incorporate reviewer suggestions

* Make OS / ENVIRONMENT doc-related

* Rephrase Ansibot-related message
---
 .github/ISSUE_TEMPLATE.md                     | 43 ++++++--------
 .github/ISSUE_TEMPLATE/bug_report.md          | 48 +++++++---------
 .../ISSUE_TEMPLATE/documentation_report.md    | 57 ++++++-------------
 .github/ISSUE_TEMPLATE/feature_request.md     | 52 +++--------------
 .github/PULL_REQUEST_TEMPLATE.md              | 30 +++++-----
 5 files changed, 76 insertions(+), 154 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
index 8242ba2e87b..ad3657dc28c 100644
--- a/.github/ISSUE_TEMPLATE.md
+++ b/.github/ISSUE_TEMPLATE.md
@@ -1,12 +1,9 @@
-<!---
-Verify first that your issue/request is not already reported on GitHub.
-THIS FORM WILL BE READ BY A MACHINE, COMPLETE ALL SECTIONS AS DESCRIBED.
-Also test if the latest release, and devel branch are affected too.
-ALWAYS add information AFTER (OUTSIDE) these html comments.
-Otherwise it may end up being automatically closed by our bot. -->
+<!--- Verify first that your issue is not already reported on GitHub -->
+<!--- Also test if the latest release and devel branch are affected too -->
+<!--- Complete *all* sections as described, this form is processed automatically -->
 
 ##### SUMMARY
-<!--- Explain the problem briefly -->
+<!--- Explain the problem briefly below -->
 
 ##### ISSUE TYPE
 <!--- Pick one below and delete the rest -->
@@ -15,44 +12,40 @@ Otherwise it may end up being automatically closed by our bot. -->
  - Documentation Report
 
 ##### COMPONENT NAME
-<!--- Insert, BELOW THIS COMMENT, the name of the module, plugin, task or feature.
-Do not include extra details here, e.g. "vyos_command" not "the network module vyos_command" or the full path-->
+<!--- Write the short name of the module, plugin, task or feature below -->
 
 ##### ANSIBLE VERSION
-<!--- Paste, BELOW THIS COMMENT, verbatim output from "ansible --version" between quotes below -->
-```
+<!--- Paste verbatim output from "ansible --version" between quotes -->
+```paste below
 
 ```
 
 ##### CONFIGURATION
-<!--- If using Ansible 2.4 or above, paste, BELOW THIS COMMENT, the results of "ansible-config dump --only-changed"
-Otherwise, mention any settings you have changed/added/removed in ansible.cfg
-(or using the ANSIBLE_* environment variables).-->
+<!--- Paste verbatim output from "ansible-config dump --only-changed" between quotes -->
+```paste below
+
+```
 
 ##### OS / ENVIRONMENT
-<!--- Mention, BELOW THIS COMMENT, the OS you are running Ansible from, and the OS you are
-managing, or say "N/A" for anything that is not platform-specific.
-Also mention the specific version of what you are trying to control,
-e.g. if this is a network bug the version of firmware on the network device.-->
+<!--- Provide all relevant information below, e.g. target OS versions, network device firmware, etc. -->
 
 ##### STEPS TO REPRODUCE
-<!--- For bugs, show exactly how to reproduce the problem, using a minimal test-case.
-For new features, show how the feature would be used. -->
+<!--- Describe exactly how to reproduce the problem, using a minimal test-case -->
 
 <!--- Paste example playbooks or commands between quotes below -->
 ```yaml
 
 ```
 
-<!--- You can also paste gist.github.com links for larger files -->
+<!--- HINT: You can paste gist.github.com links for larger files -->
 
 ##### EXPECTED RESULTS
-<!--- What did you expect to happen when running the steps above? -->
+<!--- Describe what you expected to happen when running the steps above -->
 
 ##### ACTUAL RESULTS
-<!--- What actually happened? If possible run with extra verbosity (-vvvv) -->
+<!--- Describe what actually happened. If possible run with extra verbosity (-vvvv) -->
 
-<!--- Paste verbatim command output between quotes below -->
-```
+<!--- Paste verbatim command output between quotes -->
+```paste below
 
 ```
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index a481fc9faeb..b5d7009d8a7 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,61 +1,53 @@
 ---
 name: 🐛 Bug report
 about: Create a report to help us improve
-
 ---
-
-<!---
-Verify first that your issue/request is not already reported on GitHub.
-THIS FORM WILL BE READ BY A MACHINE, COMPLETE ALL SECTIONS AS DESCRIBED.
-Also test if the latest release, and devel branch are affected too.
-ALWAYS add information AFTER (OUTSIDE) these html comments.
-Otherwise it may end up being automatically closed by our bot. -->
+<!--- Verify first that your issue is not already reported on GitHub -->
+<!--- Also test if the latest release and devel branch are affected too -->
+<!--- Complete *all* sections as described, this form is processed automatically -->
 
 ##### SUMMARY
-<!--- Explain the problem briefly -->
+<!--- Explain the problem briefly below -->
 
 ##### ISSUE TYPE
- - Bug Report
+- Bug Report
 
 ##### COMPONENT NAME
-<!--- Insert, BELOW THIS COMMENT, the name of the module, plugin, task or feature.
-Do not include extra details here, e.g. "vyos_command" not "the network module vyos_command" or the full path-->
+<!--- Write the short name of the module, plugin, task or feature below -->
 
 ##### ANSIBLE VERSION
-<!--- Paste, BELOW THIS COMMENT, verbatim output from "ansible --version" between quotes below -->
-```
+<!--- Paste verbatim output from "ansible --version" between quotes -->
+```paste below
 
 ```
 
 ##### CONFIGURATION
-<!--- If using Ansible 2.4 or above, paste, BELOW THIS COMMENT, the results of "ansible-config dump --only-changed"
-Otherwise, mention any settings you have changed/added/removed in ansible.cfg
-(or using the ANSIBLE_* environment variables).-->
+<!--- Paste verbatim output from "ansible-config dump --only-changed" between quotes -->
+```paste below
+
+```
 
 ##### OS / ENVIRONMENT
-<!--- Mention, BELOW THIS COMMENT, the OS you are running Ansible from, and the OS you are
-managing, or say "N/A" for anything that is not platform-specific.
-Also mention the specific version of what you are trying to control,
-e.g. if this is a network bug the version of firmware on the network device.-->
+<!--- Provide all relevant information below, e.g. target OS versions, network device firmware, etc. -->
 
 ##### STEPS TO REPRODUCE
-<!--- For bugs, show exactly how to reproduce the problem, using a minimal test-case.
-For new features, show how the feature would be used. -->
+<!--- Describe exactly how to reproduce the problem, using a minimal test-case -->
 
 <!--- Paste example playbooks or commands between quotes below -->
 ```yaml
 
 ```
 
-<!--- You can also paste gist.github.com links for larger files -->
+<!--- HINT: You can paste gist.github.com links for larger files -->
 
 ##### EXPECTED RESULTS
-<!--- What did you expect to happen when running the steps above? -->
+<!--- Describe what you expected to happen when running the steps above -->
+
 
 ##### ACTUAL RESULTS
-<!--- What actually happened? If possible run with extra verbosity (-vvvv) -->
+<!--- Describe what actually happened. If possible run with extra verbosity (-vvvv) -->
 
-<!--- Paste verbatim command output between quotes below -->
-```
+<!--- Paste verbatim command output between quotes -->
+```paste below
 
 ```
diff --git a/.github/ISSUE_TEMPLATE/documentation_report.md b/.github/ISSUE_TEMPLATE/documentation_report.md
index 2df08f7f360..951bd8a15db 100644
--- a/.github/ISSUE_TEMPLATE/documentation_report.md
+++ b/.github/ISSUE_TEMPLATE/documentation_report.md
@@ -1,61 +1,38 @@
 ---
 name: 📝 Documentation Report
 about: Ask us about docs
-
 ---
-
-<!---
-Verify first that your issue/request is not already reported on GitHub.
-THIS FORM WILL BE READ BY A MACHINE, COMPLETE ALL SECTIONS AS DESCRIBED.
-Also test if the latest release, and devel branch are affected too.
-ALWAYS add information AFTER (OUTSIDE) these html comments.
-Otherwise it may end up being automatically closed by our bot. -->
+<!--- Verify first that your improvement is not already reported on GitHub -->
+<!--- Also test if the latest release and devel branch are affected too -->
+<!--- Complete *all* sections as described, this form is processed automatically -->
 
 ##### SUMMARY
-<!--- Explain the problem briefly -->
+<!--- Explain the problem briefly below, add suggestions to wording or structure -->
+
+<!--- HINT: Did you know the documentation has an "Edit on GitHub" link on every page ? -->
 
 ##### ISSUE TYPE
- - Documentation Report
+- Documentation Report
 
 ##### COMPONENT NAME
-<!--- Insert, BELOW THIS COMMENT, the name of the module, plugin, task or feature.
-Do not include extra details here, e.g. "vyos_command" not "the network module vyos_command" or the full path-->
+<!--- Write the name of the rst file, module, plugin, task or feature below -->
 
 ##### ANSIBLE VERSION
-<!--- Paste, BELOW THIS COMMENT, verbatim output from "ansible --version" between quotes below -->
-```
+<!--- Paste verbatim output from "ansible --version" between quotes -->
+```paste below
 
 ```
 
 ##### CONFIGURATION
-<!--- If using Ansible 2.4 or above, paste, BELOW THIS COMMENT, the results of "ansible-config dump --only-changed"
-Otherwise, mention any settings you have changed/added/removed in ansible.cfg
-(or using the ANSIBLE_* environment variables).-->
-
-##### OS / ENVIRONMENT
-<!--- Mention, BELOW THIS COMMENT, the OS you are running Ansible from, and the OS you are
-managing, or say "N/A" for anything that is not platform-specific.
-Also mention the specific version of what you are trying to control,
-e.g. if this is a network bug the version of firmware on the network device.-->
-
-##### STEPS TO REPRODUCE
-<!--- For bugs, show exactly how to reproduce the problem, using a minimal test-case.
-For new features, show how the feature would be used. -->
-
-<!--- Paste example playbooks or commands between quotes below -->
-```yaml
+<!--- Paste verbatim output from "ansible-config dump --only-changed" between quotes -->
+```paste below
 
 ```
 
-<!--- You can also paste gist.github.com links for larger files -->
-
-##### EXPECTED RESULTS
-<!--- What did you expect to happen when running the steps above? -->
-
-##### ACTUAL RESULTS
-<!--- What actually happened? If possible run with extra verbosity (-vvvv) -->
+##### OS / ENVIRONMENT
+<!--- Provide all relevant information below, e.g. OS version, browser, etc. -->
 
-<!--- Paste verbatim command output between quotes below -->
-```
+##### ADDITIONAL INFORMATION
+<!--- Describe how this improves the documentation, e.g. before/after situation or screenshots -->
 
-```
+<!--- HINT: You can paste gist.github.com links for larger files -->
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index 8c9e2aec84b..55c861b9526 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,61 +1,25 @@
 ---
 name: ✨ Feature request
 about: Suggest an idea for this project
-
 ---
-
-<!---
-Verify first that your issue/request is not already reported on GitHub.
-THIS FORM WILL BE READ BY A MACHINE, COMPLETE ALL SECTIONS AS DESCRIBED.
-Also test if the latest release, and devel branch are affected too.
-ALWAYS add information AFTER (OUTSIDE) these html comments.
-Otherwise it may end up being automatically closed by our bot. -->
+<!--- Verify first that your feature was not already discussed on GitHub -->
+<!--- Complete *all* sections as described, this form is processed automatically -->
 
 ##### SUMMARY
-<!--- Explain the problem briefly -->
+<!--- Describe the new feature/improvement briefly below -->
 
 ##### ISSUE TYPE
- - Feature Idea
+- Feature Idea
 
 ##### COMPONENT NAME
-<!--- Insert, BELOW THIS COMMENT, the name of the module, plugin, task or feature.
-Do not include extra details here, e.g. "vyos_command" not "the network module vyos_command" or the full path-->
-
-##### ANSIBLE VERSION
-<!--- Paste, BELOW THIS COMMENT, verbatim output from "ansible --version" between quotes below -->
-```
-
-```
-
-##### CONFIGURATION
-<!--- If using Ansible 2.4 or above, paste, BELOW THIS COMMENT, the results of "ansible-config dump --only-changed"
-Otherwise, mention any settings you have changed/added/removed in ansible.cfg
-(or using the ANSIBLE_* environment variables).-->
+<!--- Write the short name of the new feature, module, plugin or task below -->
 
-##### OS / ENVIRONMENT
-<!--- Mention, BELOW THIS COMMENT, the OS you are running Ansible from, and the OS you are
-managing, or say "N/A" for anything that is not platform-specific.
-Also mention the specific version of what you are trying to control,
-e.g. if this is a network bug the version of firmware on the network device.-->
-
-##### STEPS TO REPRODUCE
-<!--- For bugs, show exactly how to reproduce the problem, using a minimal test-case.
-For new features, show how the feature would be used. -->
+##### ADDITIONAL INFORMATION
+<!--- Describe how the feature would be used, why it is needed and what it would solve -->
 
 <!--- Paste example playbooks or commands between quotes below -->
 ```yaml
 
 ```
 
-<!--- You can also paste gist.github.com links for larger files -->
-
-##### EXPECTED RESULTS
-<!--- What did you expect to happen when running the steps above? -->
-
-##### ACTUAL RESULTS
-<!--- What actually happened? If possible run with extra verbosity (-vvvv) -->
-
-<!--- Paste verbatim command output between quotes below -->
-```
-
-```
+<!--- HINT: You can also paste gist.github.com links for larger files -->
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 0ffd462b9cb..5919733a76a 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,33 +1,29 @@
 ##### SUMMARY
-<!--- Describe the change, including rationale and design decisions -->
+<!--- Describe the change below, including rationale and design decisions -->
 
-<!--- If you are fixing an existing issue, please include "Fixes #nnn" in your
-commit message and your description; but you should still explain what
-the change does.-->
+<!--- HINT: Include "Fixes #nnn" if you are fixing an existing issue -->
 
 ##### ISSUE TYPE
-<!--- Pick one below and delete the rest: -->
- - Feature Pull Request
- - New Module Pull Request
- - Bugfix Pull Request
- - Docs Pull Request
+<!--- Pick one below and delete the rest -->
+- Bugfix Pull Request
+- Docs Pull Request
+- Feature Pull Request
+- New Module Pull Request
 
 ##### COMPONENT NAME
-<!--- Name of the module, plugin, task or feature -->
+<!--- Write the short name of the module, plugin, task or feature below -->
 
 ##### ANSIBLE VERSION
-<!--- Paste verbatim output from "ansible --version" between quotes below -->
-```
+<!--- Paste verbatim output from "ansible --version" between quotes -->
+```paste below
 
 ```
 
-
 ##### ADDITIONAL INFORMATION
-<!--- Include additional information to help people understand the change here.
-For bugs that don't have a linked bug report, a step-by-step reproduction
-of the problem is helpful. -->
+<!--- Include additional information to help people understand the change here -->
+<!--- A step-by-step reproduction of the problem is helpful if there is no related issue -->
 
 <!--- Paste verbatim command output below, e.g. before and after your change -->
-```
+```paste below
 
 ```