From e9bf11f6c3897ca951ad5f9ec4a3d35ea1d4a10f Mon Sep 17 00:00:00 2001
From: Alexandra Tran <12214231+alexandratran@users.noreply.github.com>
Date: Thu, 3 Mar 2022 11:31:48 -0800
Subject: [PATCH] update PR/issue templates (#346)

* update PR/issue templates

* more edits

* minor edits

* Update .github/ISSUE_TEMPLATE/content_issue.md

Co-authored-by: rolandtyler <88206508+rolandtyler@users.noreply.github.com>

* typo

* debug CI

* remove debug and fix error

Co-authored-by: rolandtyler <88206508+rolandtyler@users.noreply.github.com>
Co-authored-by: Nicolas MASSART <nicolas.massart@consensys.net>
---
 .github/ISSUE_TEMPLATE/content_issue.md | 28 ++++------
 .github/ISSUE_TEMPLATE/tool_issue.md    | 45 +++++-----------
 .github/pull_request_template.md        | 68 +++++++++++--------------
 3 files changed, 54 insertions(+), 87 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/content_issue.md b/.github/ISSUE_TEMPLATE/content_issue.md
index 3de5d49cc..8357c3ec2 100644
--- a/.github/ISSUE_TEMPLATE/content_issue.md
+++ b/.github/ISSUE_TEMPLATE/content_issue.md
@@ -1,24 +1,22 @@
 ---
-name: Doc content issue report
+name: Documentation content issue report
 about: Create a report to help us improve our content.
 title: ''
 
 ---
 
-<!-- **IMPORTANT: this is only for reporting documentation content issues.**
+<!-- IMPORTANT: This is only for reporting documentation content issues.
 
-- Report Teku software issues at https://github.com/consensys/teku.
-- Report doc tool issues using the "Doc tool bug report" template.
+Report Teku software issues at https://github.com/consensys/teku.
+Report documentation tool issues using the "Documentation tool bug report" template.
 
-**Before creating a bug**, have you tried using the search field in the documentation
-to find what you're looking for?
+Before creating an issue, did you use the search field in the documentation to find what you're looking for?
 -->
 
 ## Describe the bug
 
-<!-- A clear and concise description of what the doc issue is.
-
-Check the issue type in the following list (insert X instead of space between [ ]): -->
+<!-- Add a clear and concise description of what the documentation issue is.
+Also, check the issue type in the following list: -->
 
 - [ ] Missing content
 - [ ] Outdated content
@@ -26,18 +24,10 @@ Check the issue type in the following list (insert X instead of space between [
 - [ ] Confusing or misleading content
 - [ ] Other
 
-## The broken page
-
-[Paste the doc site page link here.]
-
 ## Change suggestion
 
-<!-- If you know how to fix the content, you may provide a suggestion. -->
-
-## Screenshots
-
-<!-- If it helps to understand the issue, you may link an annotated screenshot or a small demo video. -->
+<!-- If you know how to fix the content, provide a suggestion. -->
 
 ## More context
 
-<!-- Add any other context about the problem here. -->
+<!-- Add any other context about the problem here, for example, screenshots or a small demo video. -->
diff --git a/.github/ISSUE_TEMPLATE/tool_issue.md b/.github/ISSUE_TEMPLATE/tool_issue.md
index db9ccb2d6..6f0e3a44f 100644
--- a/.github/ISSUE_TEMPLATE/tool_issue.md
+++ b/.github/ISSUE_TEMPLATE/tool_issue.md
@@ -1,48 +1,31 @@
 ---
-name: Doc tool bug report
-about: Create a report to help us improve our doc tools.
+name: Documentation tool bug report
+about: Create a report to help us improve our documentation tools.
 title: ''
 
 ---
 
-<!-- **IMPORTANT: this is only for reporting documentation tools bugs.**
+<!-- IMPORTANT: This is only for reporting documentation tool bugs.
 
-- Report Teku software issues at https://github.com/consensys/teku.
-- Report doc content issues using the "Doc content issue report" template.
+Report Teku software issues at https://github.com/consensys/teku.
+Report documentation content issues using the "Documentation content issue report" template.
 
-**Before creating a bug**, did you try refreshing your browser cache for our site?
+Before creating an issue, did you refresh your browser cache for the site?
 -->
 
 ## Describe the bug
 
-<!-- A clear and concise description of what the doc bug is. -->
+<!-- Add a clear and concise description of what the documentation bug is.
+Include steps to reproduce the bug and what you expected to happen. -->
 
-## The broken page
+## System settings
 
-[Paste the doc site page link here.]
+<!-- Add the following information about your system: -->
 
-## System (please complete the following information)
-
- - OS: [Windows, macOS, Linux] and its version.
- - Browser: [Chrome, Firefox, Safari,…] and its version.
- - Plugins: list plugins activated in your Browser.
-
-## To Reproduce
-
-Steps to reproduce the behavior:
-1. Go to page '…'
-2. Click on '…'
-3. Scroll down to '…'
-4. See error
-
-## Expected behavior
-
-<!-- A clear and concise description of what you expected to happen. -->
-
-## Screenshots
-
-<!-- If it helps to understand the issue, you may link an annotated screenshot or a small demo video. -->
+- OS and version:
+- Browser and version:
+- Plugins activated in your browser:
 
 ## More context
 
-<!-- Add any other context about the problem here. -->
+<!-- Add any other context about the problem here, for example, screenshots or a small demo video. -->
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 9b85f4edc..5299cb30f 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -1,65 +1,59 @@
-## Pull request checklist
+# Pull request checklist
 
-Use the following list to make sure your PR fits the Teku doc quality standard.
+Use the following template to make sure your PR fits the Teku documentation standard.
 
-### Before creating the pull request
+## Before creating the PR
 
 Make sure that:
 
-- [ ] you have read the [contribution guidelines](https://github.com/ConsenSys/doc.common/wiki/Contributing-to-Documentation).
-- [ ] you have [tested your changes locally](https://github.com/ConsenSys/doc.common/wiki/MkDocs-And-Custom-Markdown-Guide#preview-documentation-site-locally) before submitting them to the community for review.
-
-### After creating your pull request and tests finished
-
-Make sure that:
-
-- [ ] you have fixed all the issues raised by the tests, if any.
-- [ ] you have verified the rendering of your changes on
-  [ReadTheDocs.org PR preview](https://github.com/ConsenSys/doc.common/wiki/MkDocs-And-Custom-Markdown-Guide#preview-the-doc-site-for-your-pr-on-readthedocscom)
-  and updated the testing link (see [Testing](#testing)).
+- [ ] You've read the [contribution guidelines](https://consensys.net/docs/doctools/).
+- [ ] You've [previewed your changes locally](https://consensys.net/docs/doctools/en/latest/preview/old-system/#preview-locally).
 
 ## Describe the change
 
-<!-- A clear and concise description of what this PR changes in the documentation. -->
+<!-- Add a clear and concise description of what your PR changes in the documentation. -->
 
 ## Issue fixed
 
-<!-- Except for minor changes (typos, commas) it's required to have a Github issue linked to your
-pull request.
+<!-- Link to the GitHub issue that your PR addresses.
+
+Add "fixes #{your issue number}" to close the issue automatically when the PR is merged.
 
-Use the following to make Github close the issue automatically when merging the PR:
-fixes #{your issue number}
-If multiple issues are involved, use one line for each issue.
+If your PR doesn't completely fix the issue, add "see #{your issue number}" to link to the issue
+without automatically closing it. -->
 
-If you don't want to close the issue, use:
-see #{your issue number} -->
+## Impacted parts
 
-## Impacted parts <!-- check as many boxes as needed -->
+<!-- Check the item from the following lists that your PR impacts. You can check multiple boxes. -->
 
-### For content changes
+For content changes:
 
-- [ ] Doc content
-- [ ] Doc pages organisation
+- [ ] Documentation content
+- [ ] Documentation page organization
 
-### For tools changes
+For tool changes:
 
 - [ ] CircleCI workflow
-- [ ] Build and QA tools (lint, vale,…)
+- [ ] Build and QA tools (for example lint or vale)
 - [ ] MkDocs templates
 - [ ] MkDocs configuration
 - [ ] Python dependencies
 - [ ] Node dependencies and JavaScript
-- [ ] ReadTheDocs configuration
+- [ ] Read the Docs configuration
 - [ ] GitHub integration
 
-## Testing
+## After creating your PR and tests have finished
 
-<!-- Steps to follow to review and test your changes.
-Add links to preview the pages changes here.
-Link format is https://pegasys-teku--{your PR number}.org.readthedocs.build/en/{your PR number}/
-Where {your PR number} must be replaced by the number of this PR, for instance 123
--->
+Make sure that:
+
+- [ ] You've [fixed any issues](https://consensys.net/docs/doctools/en/latest/contribute/fix-cicd-errors/) raised by the tests.
+- [ ] You've [previewed your changes on Read the Docs](https://consensys.net/docs/doctools/en/latest/preview/old-system/#preview-on-read-the-docs)
+  and added a [preview link](#preview).
 
-## Screenshots / recording
+## Preview
 
-<!-- If it helps to understand your change, you may link an annotated screenshot or a small demo video. -->
+<!-- Add the link to preview your changes on Read the Docs.
+
+The link format is "https://pegasys-teku--{your PR number}.org.readthedocs.build/en/{your PR number}/",
+where {your PR number} is replaced by the number of this PR.
+-->