From 253bd2081c9e84cc02cbc0f93d1f023e9b2b573d Mon Sep 17 00:00:00 2001 From: blam Date: Fri, 18 Feb 2022 16:09:20 +0100 Subject: [PATCH 1/4] chore: deprecating the fetch:cookiecutter being installed by default Signed-off-by: blam --- plugins/scaffolder-backend/api-report.md | 29 ++++++++++++------- .../actions/builtin/createBuiltinActions.ts | 26 +++++++++++++++-- .../src/scaffolder/actions/builtin/index.ts | 4 ++- 3 files changed, 46 insertions(+), 13 deletions(-) diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index c0ff3b3f2b..1bc39ea909 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -53,17 +53,26 @@ export type ActionContext = { // @public @deprecated export type CompletedTaskState = TaskCompletionState; -// Warning: (ae-missing-release-tag) "createBuiltinActions" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) -export const createBuiltinActions: (options: { - reader: UrlReader; - integrations: ScmIntegrations; - catalogClient: CatalogApi; - containerRunner?: ContainerRunner; - config: Config; +// @public +export const createBuiltinActions: ( + options: CreateBuiltInActionsOptions, +) => TemplateAction[]; + +// @public +export interface CreateBuiltInActionsOptions { + // (undocumented) additionalTemplateFilters?: Record; -}) => TemplateAction[]; + // (undocumented) + catalogClient: CatalogApi; + // (undocumented) + config: Config; + // @deprecated (undocumented) + containerRunner?: ContainerRunner; + // (undocumented) + integrations: ScmIntegrations; + // (undocumented) + reader: UrlReader; +} // Warning: (ae-missing-release-tag) "createCatalogRegisterAction" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts index 9df2b7146e..c03ba150c2 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts @@ -49,15 +49,32 @@ import { } from './github'; import { TemplateFilter } from '../../../lib'; import { TemplateAction } from '../types'; +import { getRootLogger } from '@backstage/backend-common'; -export const createBuiltinActions = (options: { +/** + * The options passed to {@link createBuiltinActions} + * @public + */ +export interface CreateBuiltInActionsOptions { reader: UrlReader; integrations: ScmIntegrations; catalogClient: CatalogApi; + /** @deprecated when the cookiecutter action is removed this won't be necessary */ containerRunner?: ContainerRunner; config: Config; additionalTemplateFilters?: Record; -}): TemplateAction[] => { +} + +/** + * A function to generate create a list of default actions that the scaffolder provides. + * Is called internally in the default setup, but can be used when adding your own actions or overriding the default ones + * + * @public + * @returns A list of actions that can be used in the scaffolder + */ +export const createBuiltinActions = ( + options: CreateBuiltInActionsOptions, +): TemplateAction[] => { const { reader, integrations, @@ -119,6 +136,11 @@ export const createBuiltinActions = (options: { ]; if (containerRunner) { + getRootLogger().warn( + `[DEPRECATED] The fetch:cookiecutter action will be removed part of the default scaffolder actions in later versions. +You can install the package seperately and remove the containerRunner from the createBuiltInActions to remove this warning, +or you can migrate to using fetch:template https://backstage.io/docs/features/software-templates/builtin-actions#migrating-from-fetchcookiecutter-to-fetchtemplate`, + ); actions.push( createFetchCookiecutterAction({ reader, diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts index 2265f9b4f7..5f4c04cc7d 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/index.ts @@ -15,12 +15,14 @@ */ export * from './catalog'; -export { createBuiltinActions } from './createBuiltinActions'; +export * from './createBuiltinActions'; export * from './debug'; export * from './fetch'; export * from './filesystem'; export * from './publish'; export * from './github'; +/** @deprecated please add this package to your own installation manually */ export { createFetchCookiecutterAction } from '@backstage/plugin-scaffolder-backend-module-cookiecutter'; + export { runCommand } from './helpers'; From e21755c639cdebf22f2680f180a6c2a7a0590fb1 Mon Sep 17 00:00:00 2001 From: blam Date: Fri, 18 Feb 2022 16:17:23 +0100 Subject: [PATCH 2/4] chore: tidying up the fetchContents types Signed-off-by: blam --- .../src/scaffolder/actions/builtin/fetch/helpers.test.ts | 9 --------- .../src/scaffolder/actions/builtin/fetch/helpers.ts | 9 +-------- 2 files changed, 1 insertion(+), 17 deletions(-) diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts index a738afbe3f..d274ad3ba8 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.test.ts @@ -50,15 +50,6 @@ describe('fetchContent helper', () => { outputPath: os.tmpdir(), }; - it('should reject non string fetchUrls', async () => { - await expect( - fetchContents({ - ...options, - fetchUrl: false, - }), - ).rejects.toThrow('Invalid url parameter, expected string, got boolean'); - }); - it('should reject absolute file locations', async () => { await expect( fetchContents({ diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts index b56bab0d53..89d9b0171a 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts @@ -15,7 +15,6 @@ */ import { resolveSafeChildPath, UrlReader } from '@backstage/backend-common'; -import { JsonValue } from '@backstage/types'; import { InputError } from '@backstage/errors'; import { ScmIntegrations } from '@backstage/integration'; import fs from 'fs-extra'; @@ -31,15 +30,9 @@ export async function fetchContents({ reader: UrlReader; integrations: ScmIntegrations; baseUrl?: string; - fetchUrl?: JsonValue; + fetchUrl?: string; outputPath: string; }) { - if (typeof fetchUrl !== 'string') { - throw new InputError( - `Invalid url parameter, expected string, got ${typeof fetchUrl}`, - ); - } - let fetchUrlIsAbsolute = false; try { // eslint-disable-next-line no-new From 756f6cc5ef23e8ff343b7f69f199a7c3efc1997b Mon Sep 17 00:00:00 2001 From: blam Date: Fri, 18 Feb 2022 16:22:18 +0100 Subject: [PATCH 3/4] chore: added some more deprecations and fixing some more of the api-report Signed-off-by: blam --- plugins/scaffolder-backend/api-report.md | 8 +++----- .../src/scaffolder/actions/builtin/fetch/helpers.ts | 6 ++++++ .../src/scaffolder/tasks/StorageTaskBroker.ts | 4 ++-- plugins/scaffolder-backend/src/scaffolder/tasks/types.ts | 2 +- 4 files changed, 12 insertions(+), 8 deletions(-) diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index 1bc39ea909..aea6689183 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -365,9 +365,7 @@ export class DatabaseTaskStore implements TaskStore { // @public @deprecated export type DispatchResult = TaskBrokerDispatchResult; -// Warning: (ae-missing-release-tag) "fetchContents" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export function fetchContents({ reader, integrations, @@ -378,7 +376,7 @@ export function fetchContents({ reader: UrlReader; integrations: ScmIntegrations; baseUrl?: string; - fetchUrl?: JsonValue; + fetchUrl?: string; outputPath: string; }): Promise; @@ -496,7 +494,7 @@ export interface TaskBroker { unsubscribe: () => void; }; // (undocumented) - vacuumTasks(timeoutS: { timeoutS: number }): Promise; + vacuumTasks(options: { timeoutS: number }): Promise; } // @public diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts index 89d9b0171a..a01fcee6f7 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/fetch/helpers.ts @@ -20,6 +20,12 @@ import { ScmIntegrations } from '@backstage/integration'; import fs from 'fs-extra'; import path from 'path'; +/** + * A helper function that reads the contents of a directory from the given URL. + * Can be used in your own actions, and also used behind fetch:template and fetch:plain + * + * @public + */ export async function fetchContents({ reader, integrations, diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts index 49c1056727..e7fd76ea9a 100644 --- a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts +++ b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts @@ -207,8 +207,8 @@ export class StorageTaskBroker implements TaskBroker { return { unsubscribe }; } - async vacuumTasks(timeoutS: { timeoutS: number }): Promise { - const { tasks } = await this.storage.listStaleTasks(timeoutS); + async vacuumTasks(options: { timeoutS: number }): Promise { + const { tasks } = await this.storage.listStaleTasks(options); await Promise.all( tasks.map(async task => { try { diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts index c75b85f7b5..6cc3eabdc7 100644 --- a/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts +++ b/plugins/scaffolder-backend/src/scaffolder/tasks/types.ts @@ -161,7 +161,7 @@ export interface TaskBroker { dispatch( options: TaskBrokerDispatchOptions, ): Promise; - vacuumTasks(timeoutS: { timeoutS: number }): Promise; + vacuumTasks(options: { timeoutS: number }): Promise; observe( options: { taskId: string; From 6981ac4ad2d8ae212ef41b9215c84e2885528915 Mon Sep 17 00:00:00 2001 From: blam Date: Fri, 18 Feb 2022 16:28:02 +0100 Subject: [PATCH 4/4] feat: added a changeset around the fetch:cookiecutter template Signed-off-by: blam --- .changeset/many-spoons-join.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .changeset/many-spoons-join.md diff --git a/.changeset/many-spoons-join.md b/.changeset/many-spoons-join.md new file mode 100644 index 0000000000..55b59e0518 --- /dev/null +++ b/.changeset/many-spoons-join.md @@ -0,0 +1,9 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +--- + +- **DEPRECATED** - The `containerRunner` option passed to `createBuiltinActions` has now been deprecated. + +- **DEPRECATED** - The `createFetchCookiecutterAction` export has also been deprecated and will soon disappear from this plugin. + +The `fetch:cookiecutter` action will soon be removed from the default list of actions that are provided out of the box from the scaffolder plugin. It will still be supported, and maintained by the community, so you can install the package (`@backstage/plugin-scaffolder-backend-module-cookiecutter`) and pass it in as a custom action. Or you can migrate your templates to use [`fetch:template`](https://backstage.io/docs/features/software-templates/builtin-actions#migrating-from-fetchcookiecutter-to-fetchtemplate) with the `cookiecutterCompat` option.