Merge pull request #9666 from backstage/blam/deprecations/2

deprecataion: more `scaffolder-backend` deprecations
2022-02-18 16:57:11 +01:00
parent c4760992a5 6981ac4ad2
commit c654699a27
8 changed files with 68 additions and 38 deletions
@@ -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.
@@ -53,17 +53,26 @@ export type ActionContext<Input extends JsonObject> = {
 // @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<JsonObject>[];
+
+// @public
+export interface CreateBuiltInActionsOptions {
+  // (undocumented)
  additionalTemplateFilters?: Record<string, TemplateFilter>;
-}) => TemplateAction<JsonObject>[];
+  // (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)
 //
@@ -356,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,
@@ -369,7 +376,7 @@ export function fetchContents({
  reader: UrlReader;
  integrations: ScmIntegrations;
  baseUrl?: string;
-  fetchUrl?: JsonValue;
+  fetchUrl?: string;
  outputPath: string;
 }): Promise<void>;

@@ -487,7 +494,7 @@ export interface TaskBroker {
    unsubscribe: () => void;
  };
  // (undocumented)
-  vacuumTasks(timeoutS: { timeoutS: number }): Promise<void>;
+  vacuumTasks(options: { timeoutS: number }): Promise<void>;
 }

 // @public
@@ -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<string, TemplateFilter>;
-}): TemplateAction<JsonObject>[] => {
+}
+
+/**
+ * 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<JsonObject>[] => {
  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,
@@ -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({
@@ -15,12 +15,17 @@
 */

 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';
 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,
@@ -31,15 +36,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
@@ -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';
@@ -207,8 +207,8 @@ export class StorageTaskBroker implements TaskBroker {
    return { unsubscribe };
  }

-  async vacuumTasks(timeoutS: { timeoutS: number }): Promise<void> {
-    const { tasks } = await this.storage.listStaleTasks(timeoutS);
+  async vacuumTasks(options: { timeoutS: number }): Promise<void> {
+    const { tasks } = await this.storage.listStaleTasks(options);
    await Promise.all(
      tasks.map(async task => {
        try {
@@ -161,7 +161,7 @@ export interface TaskBroker {
  dispatch(
    options: TaskBrokerDispatchOptions,
  ): Promise<TaskBrokerDispatchResult>;
-  vacuumTasks(timeoutS: { timeoutS: number }): Promise<void>;
+  vacuumTasks(options: { timeoutS: number }): Promise<void>;
  observe(
    options: {
      taskId: string;