From cce755b5af900e99dbd1c1ca38509a183c279e61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 16 Nov 2022 12:10:15 +0100 Subject: [PATCH 01/12] Update versioning policy to treat utility/service API additions as non-breaking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Patrik Oldsberg Co-authored-by: Johan Haals Signed-off-by: Fredrik Adelöw --- REVIEWING.md | 31 ++++++++++++++++++++++++++++++ docs/overview/versioning-policy.md | 21 +++++++++++++++++++- 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/REVIEWING.md b/REVIEWING.md index 469ac249f7..8611bf15a4 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -171,6 +171,37 @@ Exported types can be marked with either `@public`, `@alpha` or `@beta` release If a package does not have this configuration, then all exported types are considered stable, even if they are marked as `@alpha` or `@beta`. +#### Changes that are not Considered Breaking + +There are a few exceptions that are not considered breaking in the [versioning policy](https://backstage.io/docs/overview/versioning-policy), +primarily regarding Utility APIs and Backend Service interfaces (referred to "contracts" below) that are supplied by the +Backstage core packages. + +Example of a non-breaking change to a contract which has a default +implementation, since consumers typically only interact with that contract as +callers of existing methods: + +```diff + export interface MyService { + oldMethod(): void; ++ newMethod(): void; + } +``` + +Changes such as these must still be marked with `**BREAKING PRODUCERS**:` in the +changelog, to highlight them for those who might be implementing custom +implementations of those contracts or putting mocks of the contract in tests. + +Example of a breaking change to a contract, which affects existing consumers and +therefore makes it NOT fall under these exceptions: + +```diff + export interface MyService { +- oldMethod(): void; ++ oldMethod(): Promise; + } +``` + #### Type Contract Direction An important distinction to make when looking at changes to an API Report is the direction of the contract of a changed type, that is, whether it's used as input or output from the user's point of view. In the next two sections we'll dive into the different directions of a type contract, and how it affects whether a change is breaking or not. diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index a989f104b5..7e26ad19ea 100644 --- a/docs/overview/versioning-policy.md +++ b/docs/overview/versioning-policy.md @@ -99,7 +99,7 @@ This versioning is completely decoupled from the Backstage release versioning, meaning you might for example have `@backstage/core-plugin-api` version `3.1.4` be part of the `1.12` Backstage release. -Following versioning policy applies to all packages: +The following versioning policy applies to all packages: - Breaking changes are noted in the changelog, and documentation is updated. - Breaking changes are prefixed with `**BREAKING**: ` in the changelog. @@ -120,6 +120,25 @@ For packages at version `1.0.0` or above, the following policy also applies: changes without a deprecation period, but the changes must still adhere to semver. +### Changes that are not Considered Breaking + +There are a few changes that would typically be considered breaking changes, but +that we make exceptions for. This is both to be able to evolve the project more +rapidly, also because the alternative ends up having a bigger impact on users. + +For all Utility APIs and Backend Services that _have_ a built-in implementation, +we only consider the API stability for consumers of those interfaces. This means +that it is not considered a breaking change to break the contract for producers +of the interface. + +Changes that fall under the above rule, must be marked with +`**BREAKING PRODUCERS**:` in the changelog. + +For any case of dependency injection, it is not considered a breaking change to +add a dependency on a Utility API or Backend Service that is provided by the +framework. This includes any dependency that is provided by the +`@backstage/app-defaults` and `@backstage/backend-defaults` packages. + ### Release Stages The release stages(`@alpha`, `@beta` `@public`) refers to the From 4b4bf895c5eb05298f4309d6214471070a24d141 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Wed, 16 Nov 2022 14:37:17 +0100 Subject: [PATCH 02/12] review updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Fredrik Adelöw --- REVIEWING.md | 4 ++-- docs/overview/versioning-policy.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/REVIEWING.md b/REVIEWING.md index 8611bf15a4..500e15701d 100644 --- a/REVIEWING.md +++ b/REVIEWING.md @@ -171,9 +171,9 @@ Exported types can be marked with either `@public`, `@alpha` or `@beta` release If a package does not have this configuration, then all exported types are considered stable, even if they are marked as `@alpha` or `@beta`. -#### Changes that are not Considered Breaking +#### Changes that are Not Considered Breaking -There are a few exceptions that are not considered breaking in the [versioning policy](https://backstage.io/docs/overview/versioning-policy), +There are a few exceptions that are not considered breaking in the [versioning policy](https://backstage.io/docs/overview/versioning-policy#changes-that-are-not-considered-breaking), primarily regarding Utility APIs and Backend Service interfaces (referred to "contracts" below) that are supplied by the Backstage core packages. diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index 7e26ad19ea..10ffc82188 100644 --- a/docs/overview/versioning-policy.md +++ b/docs/overview/versioning-policy.md @@ -120,7 +120,7 @@ For packages at version `1.0.0` or above, the following policy also applies: changes without a deprecation period, but the changes must still adhere to semver. -### Changes that are not Considered Breaking +### Changes that are Not Considered Breaking There are a few changes that would typically be considered breaking changes, but that we make exceptions for. This is both to be able to evolve the project more From a962ce0551ca437bde93b1f69a881d8fea9f045b Mon Sep 17 00:00:00 2001 From: Brian Fletcher Date: Wed, 16 Nov 2022 14:03:56 +0000 Subject: [PATCH 03/12] wait for initialize to complete before finalize Signed-off-by: Brian Fletcher --- .changeset/gorgeous-hairs-applaud.md | 5 +++++ .../src/indexing/BatchSearchEngineIndexer.ts | 5 +++++ 2 files changed, 10 insertions(+) create mode 100644 .changeset/gorgeous-hairs-applaud.md diff --git a/.changeset/gorgeous-hairs-applaud.md b/.changeset/gorgeous-hairs-applaud.md new file mode 100644 index 0000000000..7793c6591e --- /dev/null +++ b/.changeset/gorgeous-hairs-applaud.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-search-backend-node': patch +--- + +Wait for indexer initialization before finalizing indexing. diff --git a/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts index 24b90c2a59..0824f0ab48 100644 --- a/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts +++ b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts @@ -110,6 +110,11 @@ export abstract class BatchSearchEngineIndexer extends Writable { * @internal */ async _final(done: (error?: Error | null) => void) { + const maybeError = await this.initialized; + if (maybeError) { + done(maybeError); + return; + } try { // Index any remaining documents. if (this.currentBatch.length) { From 92ec306d7ca3e98724347c9658fcd2c827d00e52 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 16 Nov 2022 15:42:11 +0000 Subject: [PATCH 04/12] build(deps): bump loader-utils from 1.4.1 to 1.4.2 in /storybook Bumps [loader-utils](https://github.com/webpack/loader-utils) from 1.4.1 to 1.4.2. - [Release notes](https://github.com/webpack/loader-utils/releases) - [Changelog](https://github.com/webpack/loader-utils/blob/v1.4.2/CHANGELOG.md) - [Commits](https://github.com/webpack/loader-utils/compare/v1.4.1...v1.4.2) --- updated-dependencies: - dependency-name: loader-utils dependency-type: indirect ... Signed-off-by: dependabot[bot] --- storybook/yarn.lock | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/storybook/yarn.lock b/storybook/yarn.lock index b0789605a4..3317acf774 100644 --- a/storybook/yarn.lock +++ b/storybook/yarn.lock @@ -7875,28 +7875,17 @@ __metadata: linkType: hard "loader-utils@npm:^1.2.3": - version: 1.4.1 - resolution: "loader-utils@npm:1.4.1" + version: 1.4.2 + resolution: "loader-utils@npm:1.4.2" dependencies: big.js: ^5.2.2 emojis-list: ^3.0.0 json5: ^1.0.1 - checksum: ea0b648cba0194e04a90aab6270619f0e35be009e33a443d9e642e93056cd49e6ca4c9678bd1c777a2392551bc5f4d0f24a87f5040608da1274aa84c6eebb502 + checksum: eb6fb622efc0ffd1abdf68a2022f9eac62bef8ec599cf8adb75e94d1d338381780be6278534170e99edc03380a6d29bc7eb1563c89ce17c5fed3a0b17f1ad804 languageName: node linkType: hard -"loader-utils@npm:^2.0.0": - version: 2.0.2 - resolution: "loader-utils@npm:2.0.2" - dependencies: - big.js: ^5.2.2 - emojis-list: ^3.0.0 - json5: ^2.1.2 - checksum: 9078d1ed47cadc57f4c6ddbdb2add324ee7da544cea41de3b7f1128e8108fcd41cd3443a85b7ee8d7d8ac439148aa221922774efe4cf87506d4fb054d5889303 - languageName: node - linkType: hard - -"loader-utils@npm:^2.0.3": +"loader-utils@npm:^2.0.0, loader-utils@npm:^2.0.3": version: 2.0.4 resolution: "loader-utils@npm:2.0.4" dependencies: From 19356df560deb7354c3cc7204b35672a73e70732 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Thu, 17 Nov 2022 09:08:42 +0000 Subject: [PATCH 05/12] Update dependency zen-observable to ^0.9.0 Signed-off-by: Renovate Bot --- .changeset/renovate-4bb70f3.md | 17 ++++++++++++ packages/app/package.json | 2 +- packages/core-app-api/package.json | 2 +- packages/core-components/package.json | 2 +- packages/core-plugin-api/package.json | 2 +- packages/dev-utils/package.json | 2 +- packages/test-utils/package.json | 2 +- packages/types/package.json | 2 +- plugins/catalog-react/package.json | 2 +- plugins/catalog/package.json | 2 +- plugins/config-schema/package.json | 2 +- plugins/scaffolder-backend/package.json | 2 +- plugins/scaffolder/package.json | 2 +- plugins/shortcuts/package.json | 2 +- plugins/user-settings/package.json | 2 +- yarn.lock | 35 +++++++++++++++---------- 16 files changed, 52 insertions(+), 28 deletions(-) create mode 100644 .changeset/renovate-4bb70f3.md diff --git a/.changeset/renovate-4bb70f3.md b/.changeset/renovate-4bb70f3.md new file mode 100644 index 0000000000..3a9054011f --- /dev/null +++ b/.changeset/renovate-4bb70f3.md @@ -0,0 +1,17 @@ +--- +'@backstage/core-app-api': patch +'@backstage/core-components': patch +'@backstage/core-plugin-api': patch +'@backstage/dev-utils': patch +'@backstage/test-utils': patch +'@backstage/types': patch +'@backstage/plugin-catalog-react': patch +'@backstage/plugin-catalog': patch +'@backstage/plugin-config-schema': patch +'@backstage/plugin-scaffolder-backend': patch +'@backstage/plugin-scaffolder': patch +'@backstage/plugin-shortcuts': patch +'@backstage/plugin-user-settings': patch +--- + +Updated dependency `zen-observable` to `^0.9.0`. diff --git a/packages/app/package.json b/packages/app/package.json index 1d4735441a..9978a0d515 100644 --- a/packages/app/package.json +++ b/packages/app/package.json @@ -80,7 +80,7 @@ "react-router": "^6.3.0", "react-router-dom": "^6.3.0", "react-use": "^17.2.4", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "devDependencies": { "@backstage/test-utils": "workspace:^", diff --git a/packages/core-app-api/package.json b/packages/core-app-api/package.json index 95e76b4782..b5972bf308 100644 --- a/packages/core-app-api/package.json +++ b/packages/core-app-api/package.json @@ -39,7 +39,7 @@ "@types/prop-types": "^15.7.3", "prop-types": "^15.7.2", "react-use": "^17.2.4", - "zen-observable": "^0.8.15", + "zen-observable": "^0.9.0", "zod": "^3.11.6" }, "peerDependencies": { diff --git a/packages/core-components/package.json b/packages/core-components/package.json index b47473819d..4a7fec9ef1 100644 --- a/packages/core-components/package.json +++ b/packages/core-components/package.json @@ -67,7 +67,7 @@ "react-virtualized-auto-sizer": "^1.0.6", "react-window": "^1.8.6", "remark-gfm": "^3.0.1", - "zen-observable": "^0.8.15", + "zen-observable": "^0.9.0", "zod": "^3.11.6" }, "peerDependencies": { diff --git a/packages/core-plugin-api/package.json b/packages/core-plugin-api/package.json index 099b259ba7..ae9914fc77 100644 --- a/packages/core-plugin-api/package.json +++ b/packages/core-plugin-api/package.json @@ -38,7 +38,7 @@ "@backstage/version-bridge": "workspace:^", "history": "^5.0.0", "prop-types": "^15.7.2", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "@types/react": "^16.13.1 || ^17.0.0", diff --git a/packages/dev-utils/package.json b/packages/dev-utils/package.json index 7f567e61a9..08c2a2c305 100644 --- a/packages/dev-utils/package.json +++ b/packages/dev-utils/package.json @@ -47,7 +47,7 @@ "@testing-library/react": "^12.1.3", "@testing-library/user-event": "^14.0.0", "react-use": "^17.2.4", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "@types/react": "^16.13.1 || ^17.0.0", diff --git a/packages/test-utils/package.json b/packages/test-utils/package.json index 757eddd449..fb8dff4192 100644 --- a/packages/test-utils/package.json +++ b/packages/test-utils/package.json @@ -45,7 +45,7 @@ "@testing-library/react": "^12.1.3", "@testing-library/user-event": "^14.0.0", "cross-fetch": "^3.1.5", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "@types/react": "^16.13.1 || ^17.0.0", diff --git a/packages/types/package.json b/packages/types/package.json index 2cc3b0e5b8..eaf2723155 100644 --- a/packages/types/package.json +++ b/packages/types/package.json @@ -35,7 +35,7 @@ "@backstage/cli": "workspace:^", "@types/zen-observable": "^0.8.0", "luxon": "^3.0.0", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "files": [ "dist" diff --git a/plugins/catalog-react/package.json b/plugins/catalog-react/package.json index 9b8de0ce69..b4e40d8546 100644 --- a/plugins/catalog-react/package.json +++ b/plugins/catalog-react/package.json @@ -54,7 +54,7 @@ "qs": "^6.9.4", "react-use": "^17.2.4", "yaml": "^2.0.0", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "@types/react": "^16.13.1 || ^17.0.0", diff --git a/plugins/catalog/package.json b/plugins/catalog/package.json index 0220e5c244..1528737aac 100644 --- a/plugins/catalog/package.json +++ b/plugins/catalog/package.json @@ -51,7 +51,7 @@ "lodash": "^4.17.21", "react-helmet": "6.1.0", "react-use": "^17.2.4", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "@types/react": "^16.13.1 || ^17.0.0", diff --git a/plugins/config-schema/package.json b/plugins/config-schema/package.json index a7dc17deb3..c2ed4e49f7 100644 --- a/plugins/config-schema/package.json +++ b/plugins/config-schema/package.json @@ -34,7 +34,7 @@ "@material-ui/lab": "4.0.0-alpha.57", "jsonschema": "^1.2.6", "react-use": "^17.2.4", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "react": "^16.13.1 || ^17.0.0" diff --git a/plugins/scaffolder-backend/package.json b/plugins/scaffolder-backend/package.json index dcca4d382e..d5371053ca 100644 --- a/plugins/scaffolder-backend/package.json +++ b/plugins/scaffolder-backend/package.json @@ -77,7 +77,7 @@ "vm2": "^3.9.11", "winston": "^3.2.1", "yaml": "^2.0.0", - "zen-observable": "^0.8.15", + "zen-observable": "^0.9.0", "zod": "^3.11.6" }, "devDependencies": { diff --git a/plugins/scaffolder/package.json b/plugins/scaffolder/package.json index 18c522b91e..adb7461dd9 100644 --- a/plugins/scaffolder/package.json +++ b/plugins/scaffolder/package.json @@ -74,7 +74,7 @@ "react-use": "^17.2.4", "use-immer": "^0.7.0", "yaml": "^2.0.0", - "zen-observable": "^0.8.15", + "zen-observable": "^0.9.0", "zod": "^3.11.6", "zod-to-json-schema": "^3.18.1" }, diff --git a/plugins/shortcuts/package.json b/plugins/shortcuts/package.json index 40ef908779..773c6e019a 100644 --- a/plugins/shortcuts/package.json +++ b/plugins/shortcuts/package.json @@ -34,7 +34,7 @@ "react-hook-form": "^7.12.2", "react-use": "^17.2.4", "uuid": "^8.3.2", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "react": "^16.13.1 || ^17.0.0", diff --git a/plugins/user-settings/package.json b/plugins/user-settings/package.json index 1fcbed7fde..b8db3a5b03 100644 --- a/plugins/user-settings/package.json +++ b/plugins/user-settings/package.json @@ -43,7 +43,7 @@ "@material-ui/lab": "4.0.0-alpha.57", "@types/react": "^16.13.1 || ^17.0.0", "react-use": "^17.2.4", - "zen-observable": "^0.8.15" + "zen-observable": "^0.9.0" }, "peerDependencies": { "react": "^16.13.1 || ^17.0.0", diff --git a/yarn.lock b/yarn.lock index f64ac93992..b1531e5db9 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3269,7 +3269,7 @@ __metadata: react-router-dom-stable: "npm:react-router-dom@^6.3.0" react-router-stable: "npm:react-router@^6.3.0" react-use: ^17.2.4 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 zod: ^3.11.6 peerDependencies: "@types/react": ^16.13.1 || ^17.0.0 @@ -3390,7 +3390,7 @@ __metadata: react-virtualized-auto-sizer: ^1.0.6 react-window: ^1.8.6 remark-gfm: ^3.0.1 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 zod: ^3.11.6 peerDependencies: "@types/react": ^16.13.1 || ^17.0.0 @@ -3422,7 +3422,7 @@ __metadata: history: ^5.0.0 msw: ^0.48.0 prop-types: ^15.7.2 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: "@types/react": ^16.13.1 || ^17.0.0 react: ^16.13.1 || ^17.0.0 @@ -3477,7 +3477,7 @@ __metadata: "@testing-library/user-event": ^14.0.0 "@types/node": ^16.0.0 react-use: ^17.2.4 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: "@types/react": ^16.13.1 || ^17.0.0 react: ^16.13.1 || ^17.0.0 @@ -4712,7 +4712,7 @@ __metadata: react-test-renderer: ^16.13.1 react-use: ^17.2.4 yaml: ^2.0.0 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: "@types/react": ^16.13.1 || ^17.0.0 react: ^16.13.1 || ^17.0.0 @@ -4752,7 +4752,7 @@ __metadata: lodash: ^4.17.21 react-helmet: 6.1.0 react-use: ^17.2.4 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: "@types/react": ^16.13.1 || ^17.0.0 react: ^16.13.1 || ^17.0.0 @@ -5020,7 +5020,7 @@ __metadata: jsonschema: ^1.2.6 msw: ^0.48.0 react-use: ^17.2.4 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: react: ^16.13.1 || ^17.0.0 languageName: unknown @@ -6571,7 +6571,7 @@ __metadata: vm2: ^3.9.11 winston: ^3.2.1 yaml: ^2.0.0 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 zod: ^3.11.6 languageName: unknown linkType: soft @@ -6645,7 +6645,7 @@ __metadata: react-use: ^17.2.4 use-immer: ^0.7.0 yaml: ^2.0.0 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 zod: ^3.11.6 zod-to-json-schema: ^3.18.1 peerDependencies: @@ -6882,7 +6882,7 @@ __metadata: react-hook-form: ^7.12.2 react-use: ^17.2.4 uuid: ^8.3.2 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: react: ^16.13.1 || ^17.0.0 react-router: 6.0.0-beta.0 || ^6.3.0 @@ -7476,7 +7476,7 @@ __metadata: cross-fetch: ^3.1.5 msw: ^0.48.0 react-use: ^17.2.4 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: react: ^16.13.1 || ^17.0.0 react-router: 6.0.0-beta.0 || ^6.3.0 @@ -7602,7 +7602,7 @@ __metadata: "@types/node": ^16.11.26 cross-fetch: ^3.1.5 msw: ^0.48.0 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 peerDependencies: "@types/react": ^16.13.1 || ^17.0.0 react: ^16.13.1 || ^17.0.0 @@ -7628,7 +7628,7 @@ __metadata: "@backstage/cli": "workspace:^" "@types/zen-observable": ^0.8.0 luxon: ^3.0.0 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 languageName: unknown linkType: soft @@ -20886,7 +20886,7 @@ __metadata: react-router-dom: ^6.3.0 react-use: ^17.2.4 start-server-and-test: ^1.10.11 - zen-observable: ^0.8.15 + zen-observable: ^0.9.0 languageName: unknown linkType: soft @@ -37627,6 +37627,13 @@ __metadata: languageName: node linkType: hard +"zen-observable@npm:^0.9.0": + version: 0.9.0 + resolution: "zen-observable@npm:0.9.0" + checksum: d770639f7cb47c89e442b0b87e6955079b9d0f3f7da220f081c3a478ee7b837ee792be4ae8764f2d49fe0afaaa3fbcdc7a88042c3ed471df9ae551de90e82ea2 + languageName: node + linkType: hard + "zenscroll@npm:^4.0.2": version: 4.0.2 resolution: "zenscroll@npm:4.0.2" From 6574d52e6f4978d63e496d9b53d8a8e61c0e7277 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Tue, 15 Nov 2022 09:06:47 +0000 Subject: [PATCH 06/12] improve the Custom ScmAuthApi Implementation section of docs/auth Signed-off-by: Paul Cowan --- docs/auth/index.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index ab04d3ed87..bdf053c57c 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -260,7 +260,18 @@ Passport-supported authentication method. If you are using any custom authentication providers, like for example one for GitHub Enterprise, then you are likely to need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. -To set up a custom `ScmAuthApi` implementation, you'll need to add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: +To set up a custom `ScmAuthApi` implementation, you'll will need to complete the following steps which creates an example entry for a github enterprise installation: + +1. Create an additional `xxxAuthApiRef` which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: + + ```ts + const gheAuthApiRef: ApiRef = + createApiRef({ + id: 'internal.auth.ghe', + }); + ``` + +2. Add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: ```ts createApiFactory({ @@ -278,3 +289,16 @@ createApiFactory({ ), }); ``` +_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. + +3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: + + + ```ts + import { providers } from '@backstage/plugin-auth-backend'; + + // Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts + providerFactories: { + ghe: providers.github.create(), + }, + ``` \ No newline at end of file From 1a15f11d5f1c979da5b69fc7d11d205403d4512c Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Tue, 15 Nov 2022 09:37:43 +0000 Subject: [PATCH 07/12] run prettier Signed-off-by: Paul Cowan --- docs/auth/index.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index bdf053c57c..c77d42a86c 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -264,12 +264,12 @@ To set up a custom `ScmAuthApi` implementation, you'll will need to complete the 1. Create an additional `xxxAuthApiRef` which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: - ```ts - const gheAuthApiRef: ApiRef = - createApiRef({ - id: 'internal.auth.ghe', - }); - ``` +```ts +const gheAuthApiRef: ApiRef = + createApiRef({ + id: 'internal.auth.ghe', + }); +``` 2. Add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: @@ -289,16 +289,16 @@ createApiFactory({ ), }); ``` -_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. -3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: +\_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. +3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: - ```ts - import { providers } from '@backstage/plugin-auth-backend'; - - // Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts - providerFactories: { - ghe: providers.github.create(), - }, - ``` \ No newline at end of file +```ts +import { providers } from '@backstage/plugin-auth-backend'; + +// Add the following options to `createRouter` in packages/backend/src/plugins/auth.ts +providerFactories: { + ghe: providers.github.create(), +}, +``` From 1e0a64a5247a9e67c96024f1825ddb3b385a67f9 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Thu, 17 Nov 2022 10:38:32 +0000 Subject: [PATCH 08/12] update custom ScmAuthApi Implementation docs Signed-off-by: Paul Cowan --- docs/auth/index.md | 50 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index c77d42a86c..8f973a3611 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -258,11 +258,49 @@ Passport-supported authentication method. ## Custom ScmAuthApi Implementation -If you are using any custom authentication providers, like for example one for GitHub Enterprise, then you are likely to need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. +The default `ScmAuthAPi` provides integrations for `github`, `gitlab`, `azure` and `bitbucket` and is created by the following code in `packages/app/src/apis.ts`: -To set up a custom `ScmAuthApi` implementation, you'll will need to complete the following steps which creates an example entry for a github enterprise installation: +```ts +ScmAuth.createDefaultApiFactory(); +``` -1. Create an additional `xxxAuthApiRef` which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: +If you only require only a subset of these integrations then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. + +The first step is to remove the code that creates the default providers. + +```diff + import { + ScmIntegrationsApi, + scmIntegrationsApiRef, ++ ScmAuth, + } from '@backstage/integration-react'; + + export const apis: AnyApiFactory[] = [ +... ++ ScmAuth.createDefaultApiFactory(), +... + ]; +``` + +Then replace it with something like this which will create an `ApiFactory` with + +```ts +export const apis: AnyApiFactory[] = [ + createApiFactory({ + api: scmAuthApiRef, + deps: { + githubAuthApi: githubAuthApiRef, + }, + factory: ({ githubAuthApi }) => + ScmAuth.merge( + ScmAuth.forGithub(githubAuthApi), + ), + }); +``` + +If you are using any custom authentication integrations, a new provider can be added to the `ApiFactory`. + +The first step is to create a new authentication ref which follows the naming convention of `xxxAuthApiRef`. The example below is for a new github enterprise integration which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: ```ts const gheAuthApiRef: ApiRef = @@ -271,7 +309,7 @@ const gheAuthApiRef: ApiRef = }); ``` -2. Add an API factory entry to `packages/app/src/apis.ts`. The following example shows an implementation that supports both public GitHub via `githubAuthApi` as well as a GitHub Enterprise installation hosted at `ghe.example.com` via `gheAuthApi`: +The new ref is then used to add a new provider to the ApiFactory: ```ts createApiFactory({ @@ -290,9 +328,7 @@ createApiFactory({ }); ``` -\_**Warning:** You will need to remove the default `ScmAuth.createDefaultApiFactory();` with this approach. - -3. Finally you also need to add and configure another GitHub provider to the `auth-backend` using the provider ID, which in this example is `ghe`: +Finally you also need to add and configure another provider to the `auth-backend` using the provider ID, which in this example is `ghe`: ```ts import { providers } from '@backstage/plugin-auth-backend'; From cd03a88ea973b7b8e54396b361f7cf68261b1004 Mon Sep 17 00:00:00 2001 From: Paul Cowan Date: Thu, 17 Nov 2022 10:53:04 +0000 Subject: [PATCH 09/12] run prettier Signed-off-by: Paul Cowan --- docs/auth/index.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/auth/index.md b/docs/auth/index.md index 8f973a3611..5702e96cee 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -264,7 +264,7 @@ The default `ScmAuthAPi` provides integrations for `github`, `gitlab`, `azure` a ScmAuth.createDefaultApiFactory(); ``` -If you only require only a subset of these integrations then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate towards different SCM systems in a generic way, based on what resource is being accessed, and is used for example by the Scaffolder (Software Templates) and Catalog Import plugins. +If you require only a subset of these integrations, then you will need a custom implementation of the [`ScmAuthApi`](https://backstage.io/docs/reference/integration-react.scmauthapi). It is an API used to authenticate different SCM systems generically, based on what resource is being accessed, and is used for example, by the Scaffolder (Software Templates) and Catalog Import plugins. The first step is to remove the code that creates the default providers. @@ -282,7 +282,7 @@ The first step is to remove the code that creates the default providers. ]; ``` -Then replace it with something like this which will create an `ApiFactory` with +Then replace it with something like this, which will create an `ApiFactory` with only a github provider. ```ts export const apis: AnyApiFactory[] = [ @@ -298,9 +298,9 @@ export const apis: AnyApiFactory[] = [ }); ``` -If you are using any custom authentication integrations, a new provider can be added to the `ApiFactory`. +If you use any custom authentication integrations, a new provider can be added to the `ApiFactory`. -The first step is to create a new authentication ref which follows the naming convention of `xxxAuthApiRef`. The example below is for a new github enterprise integration which can be defined either inside the app itself if it's only used for this purpose, or inside an internal common package for APIs, such as `@internal/apis`: +The first step is to create a new authentication ref, which follows the naming convention of `xxxAuthApiRef`. The example below is for a new GitHub enterprise integration which can be defined either inside the app itself if it's only used for this purpose or inside a common internal package for APIs, such as `@internal/apis`: ```ts const gheAuthApiRef: ApiRef = @@ -328,7 +328,7 @@ createApiFactory({ }); ``` -Finally you also need to add and configure another provider to the `auth-backend` using the provider ID, which in this example is `ghe`: +Finally, you also need to add and configure another provider to the `auth-backend` using the provider ID, which in this example is `ghe`: ```ts import { providers } from '@backstage/plugin-auth-backend'; From 1bbe66c27b04f09a6832c4d997e1ab0f9b4fea5b Mon Sep 17 00:00:00 2001 From: Brian Fletcher Date: Thu, 17 Nov 2022 11:08:10 +0000 Subject: [PATCH 10/12] move wait into try block Signed-off-by: Brian Fletcher --- .../src/indexing/BatchSearchEngineIndexer.ts | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts index 0824f0ab48..043e2c1953 100644 --- a/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts +++ b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts @@ -110,12 +110,13 @@ export abstract class BatchSearchEngineIndexer extends Writable { * @internal */ async _final(done: (error?: Error | null) => void) { - const maybeError = await this.initialized; - if (maybeError) { - done(maybeError); - return; - } try { + const maybeError = await this.initialized; + if (maybeError) { + done(maybeError); + return; + } + // Index any remaining documents. if (this.currentBatch.length) { await this.index(this.currentBatch); From 34b039ca9f35898354bc17c751a7a334a2b0a3e6 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 17 Nov 2022 13:33:45 +0100 Subject: [PATCH 11/12] integrations: add allowedInstallationOwners to config schema Signed-off-by: Patrik Oldsberg --- .changeset/weak-ears-jam.md | 5 +++++ packages/integration/config.d.ts | 8 ++++++++ 2 files changed, 13 insertions(+) create mode 100644 .changeset/weak-ears-jam.md diff --git a/.changeset/weak-ears-jam.md b/.changeset/weak-ears-jam.md new file mode 100644 index 0000000000..8f20937998 --- /dev/null +++ b/.changeset/weak-ears-jam.md @@ -0,0 +1,5 @@ +--- +'@backstage/integration': patch +--- + +Added `integrations.github.apps.allowedInstallationOwners` to the configuration schema. diff --git a/packages/integration/config.d.ts b/packages/integration/config.d.ts index 49a121aff3..a1eb7aceb9 100644 --- a/packages/integration/config.d.ts +++ b/packages/integration/config.d.ts @@ -189,6 +189,14 @@ export interface Config { * @visibility secret */ clientSecret: string; + /** + * List of installation owners allowed to be used by this GitHub app. The GitHub UI does not provide a way to list the installations. + * However you can list the installations with the GitHub API. You can find the list of installations here: + * https://api.github.com/app/installations + * The relevant documentation for this is here. + * https://docs.github.com/en/rest/reference/apps#list-installations-for-the-authenticated-app--code-samples + */ + allowedInstallationOwners?: string[]; }>; }>; From a531879958ac25984cfcaab3e426ec7e03010602 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 17 Nov 2022 14:03:01 +0100 Subject: [PATCH 12/12] docs/getting-started: clarify yarn version Signed-off-by: Patrik Oldsberg --- docs/getting-started/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 477467bb88..16e361a19f 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -34,6 +34,7 @@ guide to do a repository-based installation. - [Package manager](https://nodejs.org/en/download/package-manager/) - [Using NodeSource packages](https://github.com/nodesource/distributions/blob/master/README.md) - `yarn` [Installation](https://classic.yarnpkg.com/en/docs/install) + - You will need to use Yarn classic to create a new project, but it can then be [migrated to Yarn 3](../tutorials/yarn-migration.md) - `docker` [installation](https://docs.docker.com/engine/install/) - `git` [installation](https://github.com/git-guides/install-git) - If the system is not directly accessible over your network the following ports