docs(troubleshooting): add a new page to help troubleshooting

Including information about GitHub token missing permissions.
Sonia-corporation · Feb 19, 2022 · c67dc84 · c67dc84
1 parent 63fb15b
commit c67dc84
Show file tree

Hide file tree

Showing 12 changed files with 35 additions and 11 deletions.
diff --git a/.releaserc.json b/.releaserc.json
@@ -76,7 +76,7 @@
     [
       "@semantic-release/git",
       {
-        "assets": ["package.json", "package-lock.json", "CHANGELOG.md", "documentation/docs/14-changelog.md"],
+        "assets": ["package.json", "package-lock.json", "CHANGELOG.md", "documentation/docs/15-changelog.md"],
         "message": "build(release): new version ${nextRelease.version}"
       }
     ],

diff --git a/documentation/docs/06-issues/01-inputs/02-stale-label-input.mdx b/documentation/docs/06-issues/01-inputs/02-stale-label-input.mdx
@@ -37,7 +37,7 @@ If not, the GitHub API will throw an error.
 ### Cache {#cache}
 
 The label will be cached during the workflow.  
-This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token.
+This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token, avoiding reaching rate limits.
 
 ### Example {#example}
 

diff --git a/documentation/docs/06-issues/01-inputs/17-limit-api-queries-count-input.mdx b/documentation/docs/06-issues/01-inputs/17-limit-api-queries-count-input.mdx
@@ -33,7 +33,7 @@ When the value is below `0`, the input will have no effect.
 ### Cache {#cache}
 
 Some queries are cached during the workflow when loading static resources like the labels.  
-This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token.
+This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token, avoiding reaching rate limits.
 
 ### Example {#example}
 

diff --git a/documentation/docs/08-pull-requests/01-inputs/02-stale-label-input.mdx b/documentation/docs/08-pull-requests/01-inputs/02-stale-label-input.mdx
@@ -43,7 +43,7 @@ You may find useful to [convert your pull requests to draft](pull-request-to-dra
 ### Cache {#cache}
 
 The label will be cached during the workflow.  
-This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token.
+This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token, avoiding reaching rate limits.
 
 ### Example {#example}
 

diff --git a/documentation/docs/08-pull-requests/01-inputs/20-limit-api-queries-count-input.mdx b/documentation/docs/08-pull-requests/01-inputs/20-limit-api-queries-count-input.mdx
@@ -33,7 +33,7 @@ When the value is below `0`, the input will have no effect.
 ### Cache {#cache}
 
 Some queries are cached during the workflow when loading static resources like the labels.  
-This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token.
+This will reduce the number of calls made to the GitHub API, which will also reduce the quotas consumed for your GitHub token, avoiding reaching rate limits.
 
 ### Example {#example}
 

diff --git a/documentation/docs/12-troubleshooting.mdx b/documentation/docs/12-troubleshooting.mdx
@@ -0,0 +1,19 @@
+---
+id: troubleshooting
+title: Troubleshooting
+description: |
+  If you need some help, you can try to find an existing solved issue here.
+tags:
+  - Troubleshooting
+  - Help
+  - Tips
+---
+
+You can find here small tips and known issues/frequently asked questions that may help you to get through this action.
+
+### The logs indicate that your issue or pull request has missing data?
+
+Make sure to use the proper [GitHub token](github-token-input), and that it has all the required [permissions](https://docs.github.com/en/rest/reference/permissions-required-for-github-apps) to be able to fetch all the information.  
+See the [original discussion](https://github.com/Sonia-corporation/stale/issues/498) to have more information.
+
+You still didn't find a way to solve your trouble? Checkout the [need help page](need-help)!
diff --git a/documentation/docs/12-need-help.mdx → documentation/docs/13-need-help.mdx b/documentation/docs/12-need-help.mdx → documentation/docs/13-need-help.mdx
diff --git a/documentation/docs/13-badge.mdx → documentation/docs/14-badge.mdx b/documentation/docs/13-badge.mdx → documentation/docs/14-badge.mdx
diff --git a/documentation/docs/14-changelog.md → documentation/docs/15-changelog.md b/documentation/docs/14-changelog.md → documentation/docs/15-changelog.md
diff --git a/documentation/docusaurus.config.js b/documentation/docusaurus.config.js
@@ -81,8 +81,8 @@ const config = {
                 label: `New issue`,
               },
               {
-                href: `https://github.com/Sonia-corporation/stale/blob/develop/CHANGELOG.md`,
-                label: `Changelog`,
+                href: `/docs/troubleshooting`,
+                label: `Troubleshooting`,
               },
               {
                 href: `/docs/need-help`,
@@ -93,6 +93,10 @@ const config = {
           },
           {
             items: [
+              {
+                href: `https://github.com/Sonia-corporation/stale/blob/develop/CHANGELOG.md`,
+                label: `Changelog`,
+              },
               {
                 label: `Blog`,
                 to: `/blog`,

diff --git a/documentation/package.json b/documentation/package.json
@@ -13,7 +13,7 @@
     "write-translations": "docusaurus write-translations",
     "write-translations:french": "npm run write-translations -- --locale fr",
     "write-heading-ids": "docusaurus write-heading-ids .",
-    "write-heading-ids:changelog": "docusaurus write-heading-ids . docs/14-changelog.md",
+    "write-heading-ids:changelog": "docusaurus write-heading-ids . docs/15-changelog.md",
     "typecheck": "tsc",
     "generate-files": "npm run generate-changelog",
     "generate-changelog": "node ./scripts/generate-changelog.js"

diff --git a/documentation/scripts/generate-changelog.js b/documentation/scripts/generate-changelog.js
@@ -6,6 +6,7 @@ const _ = require(`lodash`);
 const { getDirectoryName } = require(`./get-directory-name`);
 const CONTEXT = `generate-changelog`;
 const { execSync } = require(`child_process`);
+const CHANGELOG_PATH = `documentation/docs/15-changelog.md`;
 
 /**
  * @description
@@ -23,7 +24,7 @@ async function initialize() {
   await mergeOriginalIntoDocumentationChangelog(originalChangelog, documentationChangelog);
 
   LOGGER.debug(CONTEXT, CHALK.text(`Linting the documentation changelog...`));
-  execSync(`npm run lint:other:this -- documentation/docs/14-changelog.md`, {
+  execSync(`npm run lint:other:this -- ${CHANGELOG_PATH}`, {
     stdio: `inherit`,
   });
   LOGGER.success(CONTEXT, CHALK.text(`Documentation changelog linted`));
@@ -62,7 +63,7 @@ async function loadOriginalChangelog() {
 async function loadDocumentationChangelog() {
   LOGGER.debug(CONTEXT, CHALK.text(`Loading the documentation changelog...`));
 
-  const changelog = await FS.readFile(`documentation/docs/14-changelog.md`, `utf-8`);
+  const changelog = await FS.readFile(CHANGELOG_PATH, `utf-8`);
 
   LOGGER.success(CONTEXT, CHALK.text(`Documentation changelog loaded`));
 
@@ -78,7 +79,7 @@ async function loadDocumentationChangelog() {
 async function updateDocumentationChangelog(content) {
   LOGGER.debug(CONTEXT, CHALK.text(`Updating the documentation changelog...`));
 
-  await FS.writeFile(`documentation/docs/14-changelog.md`, content);
+  await FS.writeFile(CHANGELOG_PATH, content);
 
   LOGGER.success(CONTEXT, CHALK.text(`Documentation changelog updated`));
 }