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/.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/.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/REVIEWING.md b/REVIEWING.md index 469ac249f7..500e15701d 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#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. + +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/auth/index.md b/docs/auth/index.md index ab04d3ed87..5702e96cee 100644 --- a/docs/auth/index.md +++ b/docs/auth/index.md @@ -258,9 +258,58 @@ 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 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`: +```ts +ScmAuth.createDefaultApiFactory(); +``` + +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. + +```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 only a github provider. + +```ts +export const apis: AnyApiFactory[] = [ + createApiFactory({ + api: scmAuthApiRef, + deps: { + githubAuthApi: githubAuthApiRef, + }, + factory: ({ githubAuthApi }) => + ScmAuth.merge( + ScmAuth.forGithub(githubAuthApi), + ), + }); +``` + +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 a common internal package for APIs, such as `@internal/apis`: + +```ts +const gheAuthApiRef: ApiRef = + createApiRef({ + id: 'internal.auth.ghe', + }); +``` + +The new ref is then used to add a new provider to the ApiFactory: ```ts createApiFactory({ @@ -278,3 +327,14 @@ 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`: + +```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(), +}, +``` 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 diff --git a/docs/overview/versioning-policy.md b/docs/overview/versioning-policy.md index a989f104b5..10ffc82188 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 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/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[]; }>; }>; 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/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts index 24b90c2a59..043e2c1953 100644 --- a/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts +++ b/plugins/search-backend-node/src/indexing/BatchSearchEngineIndexer.ts @@ -111,6 +111,12 @@ export abstract class BatchSearchEngineIndexer extends Writable { */ async _final(done: (error?: Error | null) => void) { try { + const maybeError = await this.initialized; + if (maybeError) { + done(maybeError); + return; + } + // Index any remaining documents. if (this.currentBatch.length) { await this.index(this.currentBatch); 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/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: 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"