From 31fc2168d8cba6c908ffd8119a85b41545047282 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Mon, 8 Feb 2021 11:52:08 +0100 Subject: [PATCH 01/13] Fix broken links in techdocs --- microsite/sidebars.json | 5 +---- mkdocs.yml | 2 -- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index f855327627..a2cf7dedbc 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -58,7 +58,6 @@ "features/software-catalog/well-known-relations", "features/software-catalog/extending-the-model", "features/software-catalog/external-integrations", - "features/software-catalog/kubernetes-in-backstage", "features/software-catalog/software-catalog-api" ] }, @@ -161,8 +160,7 @@ "api/utility-apis", "reference/utility-apis/README", "reference/createPlugin", - "reference/createPlugin-feature-flags", - "reference/createPlugin-router" + "reference/createPlugin-feature-flags" ] }, { @@ -190,7 +188,6 @@ "architecture-decisions/adrs-adr010", "architecture-decisions/adrs-adr011" ], - "Contribute": ["../CONTRIBUTING"], "Support": ["support/support", "support/project-structure"], "Glossary": ["glossary"], "FAQ": ["FAQ"] diff --git a/mkdocs.yml b/mkdocs.yml index 6236d1c1a0..525646b33b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -102,7 +102,6 @@ nav: - Utilities: 'api/utility-apis.md' - createPlugin: 'reference/createPlugin.md' - createPlugin-feature-flags: 'reference/createPlugin-feature-flags.md' - - createPlugin-router: 'reference/createPlugin-router.md' - Backend APIs: - Backend: 'api/backend.md' - Tutorials: @@ -120,7 +119,6 @@ nav: - ADR009 - Entity References: 'architecture-decisions/adr009-entity-references.md' - ADR010 - Luxon Date Library: 'architecture-decisions/adr010-luxon-date-library.md' - ADR011 - Plugin Package Structure: 'architecture-decisions/adr011-plugin-package-structure.md' - - Contribute: '../CONTRIBUTING.md' - Support: - 'support/support.md' - 'support/project-structure.md' From 9147e9226a5c328a540be2b617d33cfc1afb7d37 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Mon, 8 Feb 2021 12:15:58 +0100 Subject: [PATCH 02/13] Adds script to verify sidebars navigation --- .github/workflows/microsite-build-check.yml | 4 ++ microsite/package.json | 3 +- microsite/scripts/verify-sidebars.js | 62 +++++++++++++++++++++ 3 files changed, 68 insertions(+), 1 deletion(-) create mode 100755 microsite/scripts/verify-sidebars.js diff --git a/.github/workflows/microsite-build-check.yml b/.github/workflows/microsite-build-check.yml index 45182229c9..a67efe9119 100644 --- a/.github/workflows/microsite-build-check.yml +++ b/.github/workflows/microsite-build-check.yml @@ -36,6 +36,10 @@ jobs: run: yarn install --frozen-lockfile working-directory: microsite + - name: verify sidebars + run: yarn verify:sidebars + working-directory: microsite + - name: prettier run: yarn prettier:check working-directory: microsite diff --git a/microsite/package.json b/microsite/package.json index cb82e6ec85..ea16fd8a32 100644 --- a/microsite/package.json +++ b/microsite/package.json @@ -11,7 +11,8 @@ "publish-gh-pages": "docusaurus-publish", "write-translations": "docusaurus-write-translations", "version": "docusaurus-version", - "rename-version": "docusaurus-rename-version" + "rename-version": "docusaurus-rename-version", + "verify:sidebars": "node ./scripts/verify-sidebars" }, "devDependencies": { "@spotify/prettier-config": "^9.0.0", diff --git a/microsite/scripts/verify-sidebars.js b/microsite/scripts/verify-sidebars.js new file mode 100755 index 0000000000..8a72d494ce --- /dev/null +++ b/microsite/scripts/verify-sidebars.js @@ -0,0 +1,62 @@ +/* + * Copyright 2020 Spotify AB + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * This script relies on docusaurus internals. It can be replaced in case + * docusaurus adds proper validation of the sidebar items. + */ + +require('@babel/polyfill'); +require('@babel/register')({ + babelrc: false, + only: [`${__dirname}/..`, `${process.cwd()}/core`], + plugins: [ + require('docusaurus/lib/server/translate-plugin.js'), + require('@babel/plugin-proposal-class-properties').default, + require('@babel/plugin-proposal-object-rest-spread').default, + ], + presets: [ + require('@babel/preset-react').default, + require('@babel/preset-env').default, + ], +}); + +const readMetadata = require('docusaurus/lib/server/readMetadata.js'); +readMetadata.generateMetadataDocs(); +const metadata = require('docusaurus/lib/core/metadata.js'); + +const errors = []; +const ids = Object.keys(metadata); +for (let id of ids) { + const { next, previous } = metadata[id]; + + if (next && !ids.includes(next)) { + errors.push(`Next ${next} does not exists in ${id}.`); + } + + if (previous && !ids.includes(previous)) { + errors.push(`Previous ${previous} does not exists in ${id}.`); + } +} + +if (errors.length) { + for (let error of errors) { + console.log(`❌ ${error}`); + } + process.exit(1); +} + +console.log('✅ All sidebar links are correct.'); From 9d6793a5ffc576ef156caa8b84177a953f94328b Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sat, 20 Feb 2021 19:36:59 +0100 Subject: [PATCH 03/13] Adds symlinks to docs in root --- docs/ADOPTERS.md | 1 + docs/CONTRIBUTING.md | 1 + docs/SECURITY.md | 1 + 3 files changed, 3 insertions(+) create mode 120000 docs/ADOPTERS.md create mode 120000 docs/CONTRIBUTING.md create mode 120000 docs/SECURITY.md diff --git a/docs/ADOPTERS.md b/docs/ADOPTERS.md new file mode 120000 index 0000000000..39390f1593 --- /dev/null +++ b/docs/ADOPTERS.md @@ -0,0 +1 @@ +../ADOPTERS.md \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 120000 index 0000000000..44fcc63439 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1 @@ +../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 120000 index 0000000000..9d571381d0 --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1 @@ +../SECURITY.md \ No newline at end of file From 3aacfc69c51eac2170353a49a9a052bb958203e2 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sat, 20 Feb 2021 19:37:35 +0100 Subject: [PATCH 04/13] Adds CONTRIBUTING back to sidebar --- microsite/sidebars.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index a2cf7dedbc..4b23af79e7 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -190,6 +190,7 @@ ], "Support": ["support/support", "support/project-structure"], "Glossary": ["glossary"], - "FAQ": ["FAQ"] + "FAQ": ["FAQ"], + "Contribute": ["CONTRIBUTING"] } } From b609e94a37252c6be8ba25d41d6756325173bc26 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sat, 20 Feb 2021 19:38:05 +0100 Subject: [PATCH 05/13] Makes verify sidebar script assume build is present --- .github/workflows/microsite-build-check.yml | 10 ++++---- microsite/scripts/verify-sidebars.js | 27 ++++++--------------- 2 files changed, 13 insertions(+), 24 deletions(-) diff --git a/.github/workflows/microsite-build-check.yml b/.github/workflows/microsite-build-check.yml index a67efe9119..a6fed59e08 100644 --- a/.github/workflows/microsite-build-check.yml +++ b/.github/workflows/microsite-build-check.yml @@ -34,11 +34,7 @@ jobs: # smaller, which make Windows builds a lot faster for the rest of the project. - name: yarn install run: yarn install --frozen-lockfile - working-directory: microsite - - - name: verify sidebars - run: yarn verify:sidebars - working-directory: microsite + working-directory: microsite - name: prettier run: yarn prettier:check @@ -47,3 +43,7 @@ jobs: - name: build microsite run: yarn build working-directory: microsite + + - name: verify sidebars + run: yarn verify:sidebars + working-directory: microsite \ No newline at end of file diff --git a/microsite/scripts/verify-sidebars.js b/microsite/scripts/verify-sidebars.js index 8a72d494ce..7c378c90cd 100755 --- a/microsite/scripts/verify-sidebars.js +++ b/microsite/scripts/verify-sidebars.js @@ -19,24 +19,13 @@ * docusaurus adds proper validation of the sidebar items. */ -require('@babel/polyfill'); -require('@babel/register')({ - babelrc: false, - only: [`${__dirname}/..`, `${process.cwd()}/core`], - plugins: [ - require('docusaurus/lib/server/translate-plugin.js'), - require('@babel/plugin-proposal-class-properties').default, - require('@babel/plugin-proposal-object-rest-spread').default, - ], - presets: [ - require('@babel/preset-react').default, - require('@babel/preset-env').default, - ], -}); - -const readMetadata = require('docusaurus/lib/server/readMetadata.js'); -readMetadata.generateMetadataDocs(); -const metadata = require('docusaurus/lib/core/metadata.js'); +let metadata; +try { + metadata = require('docusaurus/lib/core/metadata.js'); +} catch (error) { + console.log('❌ Run `yarn build` before running `yarn verify:sidebars`'); + process.exit(1); +} const errors = []; const ids = Object.keys(metadata); @@ -53,7 +42,7 @@ for (let id of ids) { } if (errors.length) { - for (let error of errors) { + for (const error of errors) { console.log(`❌ ${error}`); } process.exit(1); From 203ca79f2333488a471df8b233aa97cef01413f7 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sat, 20 Feb 2021 19:50:00 +0100 Subject: [PATCH 06/13] Replaces links to repo with relative ones to please CI --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d163a42954..1d72a39022 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -76,7 +76,7 @@ A consistent coding style is included via [EditorConfig](https://editorconfig.or If you're contributing to the backend or CLI tooling, be mindful of cross-platform support. [This](https://shapeshed.com/writing-cross-platform-node/) blog post is a good guide of what to keep in mind when writing cross-platform NodeJS. -Also be sure to skim through our [ADRs](https://github.com/backstage/backstage/tree/master/docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](https://github.com/backstage/backstage/blob/master/docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. +Also be sure to skim through our [ADRs](docs/architecture-decisions) to see if they cover what you're working on. In particular [ADR006: Avoid React.FC and React.SFC](docs/architecture-decisions/adr006-avoid-react-fc.md) is one to look out for. If there are any updates in `markdown` file please make sure to run `yarn run lint:docs`. Though it is checked on `lint-staged`. It is required to install [vale](https://docs.errata.ai/vale/install) separately and make sure it is accessed by global command. From d26b8151eb9aee35184c520ce81ca862c1690960 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sat, 20 Feb 2021 23:54:21 +0100 Subject: [PATCH 07/13] Remove CONTRIBUTING from sidebars again --- docs/ADOPTERS.md | 1 - docs/CONTRIBUTING.md | 1 - docs/SECURITY.md | 1 - microsite/sidebars.json | 3 +-- 4 files changed, 1 insertion(+), 5 deletions(-) delete mode 120000 docs/ADOPTERS.md delete mode 120000 docs/CONTRIBUTING.md delete mode 120000 docs/SECURITY.md diff --git a/docs/ADOPTERS.md b/docs/ADOPTERS.md deleted file mode 120000 index 39390f1593..0000000000 --- a/docs/ADOPTERS.md +++ /dev/null @@ -1 +0,0 @@ -../ADOPTERS.md \ No newline at end of file diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md deleted file mode 120000 index 44fcc63439..0000000000 --- a/docs/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/SECURITY.md b/docs/SECURITY.md deleted file mode 120000 index 9d571381d0..0000000000 --- a/docs/SECURITY.md +++ /dev/null @@ -1 +0,0 @@ -../SECURITY.md \ No newline at end of file diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 4b23af79e7..a2cf7dedbc 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -190,7 +190,6 @@ ], "Support": ["support/support", "support/project-structure"], "Glossary": ["glossary"], - "FAQ": ["FAQ"], - "Contribute": ["CONTRIBUTING"] + "FAQ": ["FAQ"] } } From 5021d8dbfd6ce04ecebb41ccf3d237b0281f60fc Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sun, 21 Feb 2021 00:18:18 +0100 Subject: [PATCH 08/13] Fix link to contributors --- microsite/sidebars.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 874c9cbda4..217039838c 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -13,7 +13,7 @@ "Getting Started": [ "getting-started/index", "getting-started/running-backstage-locally", - "getting-started/contributing", + "getting-started/contributors", "getting-started/create-an-app", { "type": "subcategory", From 40087721cd4471fcc5110e7244a91fe4287de745 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sun, 21 Feb 2021 12:07:38 +0100 Subject: [PATCH 09/13] Update microsite/scripts/verify-sidebars.js Co-authored-by: Adam Harvey --- microsite/scripts/verify-sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsite/scripts/verify-sidebars.js b/microsite/scripts/verify-sidebars.js index 7c378c90cd..3c15f04620 100755 --- a/microsite/scripts/verify-sidebars.js +++ b/microsite/scripts/verify-sidebars.js @@ -37,7 +37,7 @@ for (let id of ids) { } if (previous && !ids.includes(previous)) { - errors.push(`Previous ${previous} does not exists in ${id}.`); + errors.push(`Previous ${previous} does not exist in ${id}.`); } } From d2d5056f174ecbc6721e0e8abfbabd19727acd75 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sun, 21 Feb 2021 12:17:12 +0100 Subject: [PATCH 10/13] Removes trailing spaces --- .github/workflows/microsite-build-check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/microsite-build-check.yml b/.github/workflows/microsite-build-check.yml index a6fed59e08..373e2e34f6 100644 --- a/.github/workflows/microsite-build-check.yml +++ b/.github/workflows/microsite-build-check.yml @@ -34,7 +34,7 @@ jobs: # smaller, which make Windows builds a lot faster for the rest of the project. - name: yarn install run: yarn install --frozen-lockfile - working-directory: microsite + working-directory: microsite - name: prettier run: yarn prettier:check From 0bdfc9ca6313b53bd415a2697f65498262137324 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Sun, 21 Feb 2021 12:18:35 +0100 Subject: [PATCH 11/13] Fix message on verify script --- microsite/scripts/verify-sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsite/scripts/verify-sidebars.js b/microsite/scripts/verify-sidebars.js index 3c15f04620..a82780135f 100755 --- a/microsite/scripts/verify-sidebars.js +++ b/microsite/scripts/verify-sidebars.js @@ -33,7 +33,7 @@ for (let id of ids) { const { next, previous } = metadata[id]; if (next && !ids.includes(next)) { - errors.push(`Next ${next} does not exists in ${id}.`); + errors.push(`Next ${next} does not exist in ${id}.`); } if (previous && !ids.includes(previous)) { From 7e9928ffd90265bcb3919eb0beb496322459fe63 Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Tue, 23 Feb 2021 18:22:41 +0100 Subject: [PATCH 12/13] Removes offending spaces --- .github/workflows/microsite-build-check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/microsite-build-check.yml b/.github/workflows/microsite-build-check.yml index 373e2e34f6..23619420ca 100644 --- a/.github/workflows/microsite-build-check.yml +++ b/.github/workflows/microsite-build-check.yml @@ -46,4 +46,4 @@ jobs: - name: verify sidebars run: yarn verify:sidebars - working-directory: microsite \ No newline at end of file + working-directory: microsite \ No newline at end of file From cb6d22351c0cf7dfeda93ea7dd648d07cfe7509a Mon Sep 17 00:00:00 2001 From: Juan Lulkin Date: Tue, 23 Feb 2021 18:31:33 +0100 Subject: [PATCH 13/13] Adds a line break to workflow file --- .github/workflows/microsite-build-check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/microsite-build-check.yml b/.github/workflows/microsite-build-check.yml index 23619420ca..881a7ca5e4 100644 --- a/.github/workflows/microsite-build-check.yml +++ b/.github/workflows/microsite-build-check.yml @@ -46,4 +46,4 @@ jobs: - name: verify sidebars run: yarn verify:sidebars - working-directory: microsite \ No newline at end of file + working-directory: microsite