feat: add docs and forum variables for increased flexibility

Olivr · Jun 7, 2022 · 6d04346 · 6d04346
1 parent 1d9859b
commit 6d04346
Show file tree

Hide file tree

Showing 7 changed files with 49 additions and 20 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -7,7 +7,10 @@ body:
     attributes:
       value: >
         **Before** opening a new bug report, please search for relevant keywords in the
-        [existing issues](../issues) so you do not submit a duplicate report.
+        [existing issues](https://github.com/{{repo_owner}}/{{repo_name}}/issues)
+        and in our
+        [forum]({{forum_url}})
+        so you do not submit a duplicate report.
 
   - type: textarea
     validations:
@@ -61,11 +64,13 @@ body:
         - label: >
             I have searched for similar requests in the
             [existing issues](https://github.com/{{repo_owner}}/{{repo_name}}/issues)
+            and in the
+            [forum]({{forum_url}}).
           required: true
 
         # yamllint disable rule:line-length
         - label: >
             I agree to follow this project's
-            [Code of Conduct](https://github.com/{{repo_owner}}/{{repo_name}}/blob/main/docs/CODE_OF_CONDUCT.md)
+            [Code of Conduct]({{docs_base_url}}/docs/CODE_OF_CONDUCT.{{docs_extension}})
           required: true
         # yamllint enable rule:line-length
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml
@@ -1,14 +1,22 @@
 ---
 name: Feature request
-description: Tell us how {{project_name}} can serve you better
+description: >
+  Tell us how {{project_name}} can serve you better.
 labels: [enhancement]
 body:
   - type: markdown
     attributes:
       value: >
         **Before** opening a new feature request, please search for relevant keywords in the
-        [existing issues](https://github.com/{{repo_owner}}/{{repo_name}}/issues) so you do not
-        submit a duplicate request.
+        [existing issues](https://github.com/{{repo_owner}}/{{repo_name}}/issues)
+        and in our
+        [forum]({{forum_url}})
+        so you do not submit a duplicate request.
+
+        > If your lack the information to fill the fields below, maybe you ought to discuss it in
+        our
+        [forum]({{forum_url}})
+        first.
 
   - type: textarea
     validations:
@@ -62,12 +70,13 @@ body:
       options:
         - label: >
             I have searched for similar requests in the
-            [existing issues](https://github.com/{{repo_owner}}/{{repo_name}}/issues)
+            [existing issues](https://github.com/{{repo_owner}}/{{repo_name}}/issues) and in the
+            [forum]({{forum_url}}).
           required: true
 
         # yamllint disable rule:line-length
         - label: >
             I agree to follow this project's
-            [Code of Conduct](https://github.com/{{repo_owner}}/{{repo_name}}/blob/main/docs/CODE_OF_CONDUCT.md)
+            [Code of Conduct]({{docs_base_url}}/docs/CODE_OF_CONDUCT.{{docs_extension}})
           required: true
         # yamllint enable rule:line-length
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,5 +1,6 @@
 <!---
-IMPORTANT: Please read our contributing guidelines first (https://github.com/{{repo_owner}}/{{repo_name}}/blob/main/docs/CONTRIBUTING.md).
+⚠️ Please first read our contributing guidelines:
+{{docs_base_url}}/docs/CONTRIBUTING.{{docs_extension}}
 --->
 
 # Pull request
@@ -33,7 +34,7 @@ What types of changes does your code introduce? Put an `x` in all the boxes that
 Go over all the following points, and put an `x` in all the boxes that apply.
 -->
 
-- [ ] I have read the **docs/CONTRIBUTING.md** document.
-- [ ] I have updated the documentation accordingly.
 - [ ] I have added tests to cover my changes (if applicable).
 - [ ] All new and existing tests passed (if applicable).
+- [ ] I have updated the documentation accordingly.
+- [ ] I have read the [contributing guidelines]({{docs_base_url}}/docs/CONTRIBUTING.{{docs_extension}}) and agree to its terms (namely the [License]({{docs_base_url}}/LICENSE.{{docs_extension}}) and the [Code of Conduct]({{docs_base_url}}/docs/CODE_OF_CONDUCT.{{docs_extension}})).
diff --git a/.github/workflows/issue-voting.yaml b/.github/workflows/issue-voting.yaml
@@ -51,6 +51,9 @@ jobs:
 
             - Please **do** consider contributing with a pull request to resolve this issue.
 
+            - Please **do** follow our
+            [Code of Conduct]({{docs_base_url}}/docs/CODE_OF_CONDUCT.{{docs_extension}}).
+
 
             ## Don'ts
 

diff --git a/.github/workflows/pr-helper.yaml b/.github/workflows/pr-helper.yaml
@@ -75,6 +75,6 @@ jobs:
               </details>
 
             Read more about our recommended [pull request
-            process](https://github.com/${{github.repository}}/blob/main/docs/CONTRIBUTING.md#pull-request-process).
+            process]({{docs_base_url}}/docs/CONTRIBUTING.{{docs_extension}}#pull-request-process).
           reactions: eyes
           token: ${{ steps.generate_token.outputs.token }}
diff --git a/README.md b/README.md
@@ -4,12 +4,23 @@
 
 1. Search/replace for these variables:
 
-   - `{{repo_owner}}` (GitHub repository username)
-   - `{{repo_name}}` (GitHub repository name)
-   - `{{project_name}}` (Project name)
-   - `{{project_tagline}}` (Project tagline)
-   - `{{security_email}}` (Email to send vulnerabilities add `-noreply` before the `@`)
-   - `{{author_name}}` (Your name)
+   - `{{repo_owner}}` - GitHub repository username
+   - `{{repo_name}}` - GitHub repository name
+   - `{{project_name}}` - Project name
+   - `{{project_tagline}}` - Project tagline
+   - `{{security_email}}` - Email to send vulnerabilities add `-noreply` before the `@`
+   - `{{author_name}}` - Your name
+   - `{{docs_base_url}}` - Base URL to the documentation (no trailing slash). It could be:
+     - `https://<repo_owner>.github.io/<repo_name>` (GitHub Pages default)
+     - `https://<your_domain>` (GitHub Pages with CNAME file)
+     - `https://github.com/<repo_owner>/<repo_name>/blob/main` (if you removed/don't want the documentation site)
+   - `{{docs_extension}}` - Should be `html` if you use the documentation site, otherwise `md`
+   - `{{forum_url}}` - URL to your forum for users to ask questions. It could be:
+     - `https://github.com/<repo_owner>/<repo_name>/discussions` (if you enabled the discussions feature on your repo)
+     - `https://github.com/orgs/<repo_owner>/discussions` (if you enabled the discussions feature at your org level)
+     - `https://<your_domain>` (if you maintain a separate discussion forum, or a link to your community on Slack, Discord, etc.)
+
+   > For any decent-sized project, it is better to **own** your brand and use your own domain rather than GitHub links.
 
 2. Remove this README.md and move docs/README.md to the root
 

diff --git a/docs/README.md b/docs/README.md
@@ -10,16 +10,16 @@ For help, please create a new issue on this GitHub repository.
 
 ## Contributing
 
-All contributions are welcome! Please see the [/docs/CONTRIBUTING.md](/docs/CONTRIBUTING.md)
+All contributions are welcome! Please see our [contributing guidelines]({{docs_base_url}}/docs/CONTRIBUTING.{{docs_extension}})
 
 ![Star this repository](https://raw.githubusercontent.com/politician/politician/main/img/star_repo.gif)
 
 ## Fork
 
-If you want to [fork this repository](https://github.com/{{repo_owner}}/{{repo_name}}/fork) and modify it for your own personal/commercial usage, please do so freely, it is [licensed accordingly](/LICENSE.md).
+If you want to [fork this repository](https://github.com/{{repo_owner}}/{{repo_name}}/fork) and modify it for your own personal/commercial usage, please do so freely, it is [licensed accordingly]({{docs_base_url}}/LICENSE.{{docs_extension}}).
 
 > 💡 Consider contributing back your changes if they will benefit the wider community.
 
 ## License
 
-[![Apache 2.0 license](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](/LICENSE.md) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2F{{repo_user}}%2F{{repo_name}}.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2F{{repo_user}}%2F{{repo_name}}?ref=badge_shield)
+[![Apache 2.0 license](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)]({{docs_base_url}}/LICENSE.{{docs_extension}}) [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2F{{repo_user}}%2F{{repo_name}}.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2F{{repo_user}}%2F{{repo_name}}?ref=badge_shield)