docs: adjust guidelines (#4113)

Small adjustments to the guidelines layout and additional guidelines added.

cmd/authelia-gen/const.go

@@ -10,7 +10,7 @@ const (
 	fileCICommitLintConfig = "web/.commitlintrc.js"
 	fileWebI18NIndex       = "web/src/i18n/index.ts"
 
-	fileDocsCommitMessageGuidelines = "docs/content/en/contributing/development/guidelines-commit-message.md"
+	fileDocsCommitMessageGuidelines = "docs/content/en/contributing/guidelines/commit-message.md"
 
 	fileDocsConfigKeys = "docs/data/configkeys.json"
 	fileCodeConfigKeys = "internal/configuration/schema/keys.go"

cmd/authelia-gen/templates/dot_commitlintrc.js.tmpl

@@ -21,5 +21,5 @@ module.exports = {
         ],
     },
     defaultIgnores: true,
-    helpUrl: "https://www.authelia.com/contributing/development/guidelines-commit-message/",
+    helpUrl: "https://www.authelia.com/contributing/guidelines/commit-message/",
 };

docs/content/en/blog/pre-release-notes-4.37/index.md

@@ -13,8 +13,9 @@ pinned: false
 homepage: false
 ---
 
-Authelia 4.37 is just around the corner. This version has several additional features and improvements to existing
+Authelia [4.37](https://github.com/authelia/authelia/milestone/16) is just around the corner. This version has several
-features. In this blog post we'll discuss the new features and roughly what it means for users.
+additional features and improvements to existing features. In this blog post we'll discuss the new features and roughly
+what it means for users.
 
 _**Note:** These features are still subject to change however it represents the most likely features._
 

docs/content/en/contributing/guidelines/_index.md

@@ -0,0 +1,9 @@
+---
+title: "Guidelines"
+description: "Contributing Guidelines"
+lead: ""
+date: 2022-06-15T17:51:47+10:00
+draft: false
+images: []
+weight: 300
+---

docs/content/en/contributing/guidelines/commit-message.md

@@ -1,5 +1,5 @@
 ---
-title: "Commit Message Guidelines"
+title: "Commit Message"
 description: "Authelia Development Commit Message Guidelines"
 lead: "This section covers the git commit message guidelines we use for development."
 date: 2021-01-30T19:29:07+11:00
@@ -7,8 +7,8 @@ draft: false
 images: []
 menu:
   contributing:
-    parent: "development"
+    parent: "guidelines"
-weight: 231
+weight: 320
 toc: true
 aliases:
   - /docs/contributing/commitmsg-guidelines.html

docs/content/en/contributing/guidelines/documentation.md

@@ -0,0 +1,32 @@
+---
+title: "Documentation"
+description: "Authelia Development Documentation Guidelines"
+lead: "This section covers the guidelines we use when writing documentation."
+date: 2021-01-30T19:29:07+11:00
+draft: false
+images: []
+menu:
+  contributing:
+    parent: "guidelines"
+weight: 320
+toc: true
+---
+
+## Domains
+
+Always use the generic domain (or subdomain of) `example.com` in documentation.
+
+If it's necessary to utilize more than one domain please ask for specific feedback in any PR.
+
+## Certificates
+
+When including certificates in documentation always ensure they are valid for 1 year starting at `Jan 1 00:00:00 1970`.
+This ensures the certificate is not valid for multiple reasons.
+
+In addition the guidance for [Private Keys](#private-keys) should be followed.
+
+## Private Keys
+
+Always append invalid data to the END of the PEM block before the base64 padding `=` (if present). The suggested
+text is `^invalid DO NOT USE`. This both has an invalid base64 character `^` and has information to communicate that
+users should not use the PEM block.

docs/content/en/contributing/guidelines/introduction.md

@@ -0,0 +1,21 @@
+---
+title: "Guidelines"
+description: "An introduction into guidelines for contributing to the Authelia project."
+lead: "An introduction into guidelines for contributing to the Authelia project."
+date: 2022-06-15T17:51:47+10:00
+draft: false
+images: []
+menu:
+  contributing:
+    parent: "guidelines"
+weight: 310
+toc: true
+---
+
+The guidelines section contains various guidelines for contributing to Authelia. We implement various guidelines via
+automatic processes that will provide feedback in the PR, but this does not cover every situation. You will find both
+those which are automated and those which are not in this section.
+
+While it's expected that people aim to follow all of these guidelines we understand that there are logical exceptions to
+all guidelines and if it makes sense we're likely to agree with you. So if you find a situation where it doesn't make
+sense to follow one just let us know your reasoning when you make a PR if it's not obvious.

docs/content/en/contributing/guidelines/pull-request.md

@@ -1,5 +1,5 @@
 ---
-title: "Pull Request Guidelines"
+title: "Pull Request"
 description: "Authelia Development Pull Request Guidelines"
 lead: "This section covers the pull request guidelines."
 date: 2022-06-15T17:51:47+10:00
@@ -7,9 +7,11 @@ draft: false
 images: []
 menu:
   contributing:
-    parent: "development"
+    parent: "guidelines"
-weight: 232
+weight: 320
 toc: true
+aliases:
+  - /contributing/development/pull-request/
 ---
 
 [Pull Request] guidelines are in place in order to maintain consistency and clearly communicate our process for

docs/content/en/contributing/guidelines/style.md

@@ -1,5 +1,5 @@
 ---
-title: "Style Guidelines"
+title: "Style"
 description: "Authelia Development Style Guidelines"
 lead: "This section covers the style guidelines we use for development."
 date: 2021-04-11T21:25:03+10:00
@@ -7,17 +7,18 @@ draft: false
 images: []
 menu:
   contributing:
-    parent: "development"
+    parent: "guidelines"
-weight: 230
+weight: 320
 toc: true
 aliases:
   - /docs/contributing/style-guide.html
+  - /contributing/development/guidelines-style/
 ---
 
 This is a general guide to the code style we aim to abide by. This is by no means an exhaustive list and we're
 constantly changing and improving it. This is also a work in progress document.
 
-For our commit messages please see our [Commit Message Guidelines](guidelines-commit-message.md).
+For our commit messages please see our [Commit Message Guidelines](../guidelines/commit-message.md).
 
 ## Tools
 

docs/content/en/contributing/prologue/documentation.md

@@ -38,14 +38,12 @@ It's relatively easy to run the __Authelia__ website locally to test out the cha
 The following steps will allow you to run the website on the localhost and view it live in your browser:
 
 1. Run the following commands:
-
+    ```bash
-  ```bash
+    git clone https://github.com/authelia/authelia.git
-  git clone https://github.com/authelia/authelia.git
+    cd authelia/docs
-  cd authelia/docs
+    npm run install
-  npm run install
+    npm run start
-  npm run start
+    ```
-  ```
-
 2. Visit [http://localhost:1313/](http://localhost:1313/) in your browser.
 3. Modify pages to see the effects live in your browser.
 

docs/content/en/reference/cli/authelia-gen/authelia-gen.md

@@ -32,7 +32,7 @@ authelia-gen [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_code.md

@@ -38,7 +38,7 @@ authelia-gen code [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_code_keys.md

@@ -38,7 +38,7 @@ authelia-gen code keys [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_code_scripts.md

@@ -38,7 +38,7 @@ authelia-gen code scripts [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_commit-lint.md

@@ -38,7 +38,7 @@ authelia-gen commit-lint [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_docs.md

@@ -38,7 +38,7 @@ authelia-gen docs [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_docs_cli.md

@@ -38,7 +38,7 @@ authelia-gen docs cli [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_docs_date.md

@@ -40,7 +40,7 @@ authelia-gen docs date [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_docs_keys.md

@@ -38,7 +38,7 @@ authelia-gen docs keys [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_github.md

@@ -38,7 +38,7 @@ authelia-gen github [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_github_issue-templates.md

@@ -38,7 +38,7 @@ authelia-gen github issue-templates [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_github_issue-templates_bug-report.md

@@ -38,7 +38,7 @@ authelia-gen github issue-templates bug-report [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_github_issue-templates_feature-request.md

@@ -38,7 +38,7 @@ authelia-gen github issue-templates feature-request [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

docs/content/en/reference/cli/authelia-gen/authelia-gen_locales.md

@@ -38,7 +38,7 @@ authelia-gen locales [flags]
       --file.bug-report string                   Sets the path of the bug report issue template file (default ".github/ISSUE_TEMPLATE/bug-report.yml")
       --file.commit-lint-config string           The commit lint javascript configuration file in relation to the root (default "web/.commitlintrc.js")
       --file.configuration-keys string           Sets the path of the keys file (default "internal/configuration/schema/keys.go")
-      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/development/guidelines-commit-message.md")
+      --file.docs-commit-msg-guidelines string   The commit message guidelines documentation file in relation to the root (default "docs/content/en/contributing/guidelines/commit-message.md")
       --file.docs-keys string                    Sets the path of the docs keys file (default "docs/data/configkeys.json")
       --file.docs.data.languages string          The languages docs data file in relation to the docs data folder (default "docs/data/languages.json")
       --file.feature-request string              Sets the path of the feature request issue template file (default ".github/ISSUE_TEMPLATE/feature-request.yml")

web/.commitlintrc.js

@@ -54,5 +54,5 @@ module.exports = {
         ],
     },
     defaultIgnores: true,
-    helpUrl: "https://www.authelia.com/contributing/development/guidelines-commit-message/",
+    helpUrl: "https://www.authelia.com/contributing/guidelines/commit-message/",
 };