diff --git a/.changeset/lucky-kangaroos-sneeze.md b/.changeset/lucky-kangaroos-sneeze.md new file mode 100644 index 0000000000..badcd8a5cf --- /dev/null +++ b/.changeset/lucky-kangaroos-sneeze.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-scaffolder-backend': patch +'@backstage/plugin-scaffolder-common': patch +--- + +Adding some documentation for exported things diff --git a/plugins/scaffolder-backend/api-report.md b/plugins/scaffolder-backend/api-report.md index 6934f2ef83..c0d3595503 100644 --- a/plugins/scaffolder-backend/api-report.md +++ b/plugins/scaffolder-backend/api-report.md @@ -49,15 +49,10 @@ export const createBuiltinActions: ( // @public export interface CreateBuiltInActionsOptions { - // (undocumented) additionalTemplateFilters?: Record; - // (undocumented) catalogClient: CatalogApi; - // (undocumented) config: Config; - // (undocumented) integrations: ScmIntegrations; - // (undocumented) reader: UrlReader; } @@ -142,19 +137,16 @@ export function createGithubActionsDispatchAction(options: { token?: string | undefined; }>; -// @public (undocumented) +// @public export interface CreateGithubPullRequestActionOptions { - // (undocumented) clientFactory?: ( input: CreateGithubPullRequestClientFactoryInput, ) => Promise; - // (undocumented) githubCredentialsProvider?: GithubCredentialsProvider; - // (undocumented) integrations: ScmIntegrationRegistry; } -// @public (undocumented) +// @public export type CreateGithubPullRequestClientFactoryInput = { integrations: ScmIntegrationRegistry; githubCredentialsProvider?: GithubCredentialsProvider; @@ -278,7 +270,7 @@ export const createPublishGitlabMergeRequestAction: (options: { token?: string | undefined; }>; -// @public (undocumented) +// @public export function createRouter(options: RouterOptions): Promise; // @public @@ -298,11 +290,8 @@ export type CreateWorkerOptions = { // @public export interface CurrentClaimedTask { - // (undocumented) secrets?: TaskSecrets; - // (undocumented) spec: TaskSpec; - // (undocumented) taskId: string; } diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts index d7f15cdf13..250a2b4b9e 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/createBuiltinActions.ts @@ -54,10 +54,26 @@ import { TemplateAction } from '../types'; * @public */ export interface CreateBuiltInActionsOptions { + /** + * The {@link @backstage/backend-common#UrlReader} interface that will be used in the default actions. + */ reader: UrlReader; + /** + * The {@link @backstage/integrations#ScmIntegrations} that will be used in the default actions. + */ integrations: ScmIntegrations; + /** + * The {@link @backstage/catalog-client#CatalogApi} that will be used in the default actions. + */ catalogClient: CatalogApi; + /** + * The {@link @backstage/config#Config} that will be used in the default actions. + */ config: Config; + /** + * Additional custom filters that will be passed to the nunjucks template engine for use in + * Template Manifests and also template skeleton files when using `fetch:template`. + */ additionalTemplateFilters?: Record; } diff --git a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts index 2ce8e1d81e..d46457ee1b 100644 --- a/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts +++ b/plugins/scaffolder-backend/src/scaffolder/actions/builtin/publish/githubPullRequest.ts @@ -41,7 +41,10 @@ export interface OctokitWithPullRequestPluginClient { } | null>; } -/** @public */ +/** + * The options passed to the client factory function. + * @public + */ export type CreateGithubPullRequestClientFactoryInput = { integrations: ScmIntegrationRegistry; githubCredentialsProvider?: GithubCredentialsProvider; @@ -74,10 +77,22 @@ export const defaultClientFactory = async ({ return new OctokitPR(octokitOptions); }; -/** @public */ +/** + * The options passed to {@link createPublishGithubPullRequestAction} method + * @public + */ export interface CreateGithubPullRequestActionOptions { + /** + * An instance of {@link @backstage/integration#ScmIntegrationRegistry} that will be used in the action. + */ integrations: ScmIntegrationRegistry; + /** + * An instance of {@link @backstage/integration#GithubCredentialsProvider} that will be used to get credentials for the action. + */ githubCredentialsProvider?: GithubCredentialsProvider; + /** + * A method to return the Octokit client with the Pull Request Plugin. + */ clientFactory?: ( input: CreateGithubPullRequestClientFactoryInput, ) => Promise; diff --git a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts index 1399c25118..a92d6abdb8 100644 --- a/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts +++ b/plugins/scaffolder-backend/src/scaffolder/tasks/StorageTaskBroker.ts @@ -115,8 +115,17 @@ export class TaskManager implements TaskContext { * @public */ export interface CurrentClaimedTask { + /** + * The TaskSpec of the current claimed task. + */ spec: TaskSpec; + /** + * The uuid of the current claimed task. + */ taskId: string; + /** + * The secrets that are stored with the task. + */ secrets?: TaskSecrets; } @@ -135,6 +144,9 @@ export class StorageTaskBroker implements TaskBroker { ) {} private deferredDispatch = defer(); + /** + * {@inheritdoc TaskBroker.claim} + */ async claim(): Promise { for (;;) { const pendingTask = await this.storage.claimTask(); @@ -154,6 +166,9 @@ export class StorageTaskBroker implements TaskBroker { } } + /** + * {@inheritdoc TaskBroker.dispatch} + */ async dispatch( options: TaskBrokerDispatchOptions, ): Promise<{ taskId: string }> { @@ -164,10 +179,16 @@ export class StorageTaskBroker implements TaskBroker { }; } + /** + * {@inheritdoc TaskBroker.get} + */ async get(taskId: string): Promise { return this.storage.getTask(taskId); } + /** + * {@inheritdoc TaskBroker.event$} + */ event$(options: { taskId: string; after?: number; @@ -197,6 +218,9 @@ export class StorageTaskBroker implements TaskBroker { }); } + /** + * {@inheritdoc TaskBroker.vacuumTasks} + */ async vacuumTasks(options: { timeoutS: number }): Promise { const { tasks } = await this.storage.listStaleTasks(options); await Promise.all( diff --git a/plugins/scaffolder-backend/src/service/router.ts b/plugins/scaffolder-backend/src/service/router.ts index cf073b551b..e7413b3a87 100644 --- a/plugins/scaffolder-backend/src/service/router.ts +++ b/plugins/scaffolder-backend/src/service/router.ts @@ -62,7 +62,10 @@ function isSupportedTemplate(entity: TemplateEntityV1beta3) { return entity.apiVersion === 'scaffolder.backstage.io/v1beta3'; } -/** @public */ +/** + * A method to create a router for the scaffolder backend plugin. + * @public + */ export async function createRouter( options: RouterOptions, ): Promise { diff --git a/plugins/scaffolder-common/api-report.md b/plugins/scaffolder-common/api-report.md index 6148440e6d..532e72d3fd 100644 --- a/plugins/scaffolder-common/api-report.md +++ b/plugins/scaffolder-common/api-report.md @@ -13,41 +13,28 @@ export type TaskSpec = TaskSpecV1beta3; // @public export interface TaskSpecV1beta3 { - // (undocumented) apiVersion: 'scaffolder.backstage.io/v1beta3'; - // (undocumented) output: { [name: string]: JsonValue; }; - // (undocumented) parameters: JsonObject; - // (undocumented) steps: TaskStep[]; - // (undocumented) templateInfo?: TemplateInfo; } // @public export interface TaskStep { - // (undocumented) action: string; - // (undocumented) id: string; - // (undocumented) if?: string | boolean; - // (undocumented) input?: JsonObject; - // (undocumented) name: string; } // @public export interface TemplateEntityV1beta3 extends Entity { - // (undocumented) apiVersion: 'scaffolder.backstage.io/v1beta3'; - // (undocumented) kind: 'Template'; - // (undocumented) spec: { type: string; parameters?: JsonObject | JsonObject[]; diff --git a/plugins/scaffolder-common/src/TaskSpec.ts b/plugins/scaffolder-common/src/TaskSpec.ts index 326bb60ef6..e745964ff7 100644 --- a/plugins/scaffolder-common/src/TaskSpec.ts +++ b/plugins/scaffolder-common/src/TaskSpec.ts @@ -23,7 +23,13 @@ import { JsonValue, JsonObject } from '@backstage/types'; * @public */ export type TemplateInfo = { + /** + * The entityRef of the template + */ entityRef: string; + /** + * Where the template is stored, so we can resolve relative paths for things like `fetch:template` paths. + */ baseUrl?: string; }; @@ -33,10 +39,25 @@ export type TemplateInfo = { * @public */ export interface TaskStep { + /** + * A unqiue identifier for this step. + */ id: string; + /** + * A display name to show the user. + */ name: string; + /** + * The underlying action ID that will be called as part of running this step. + */ action: string; + /** + * Additional data that will be passed to the action. + */ input?: JsonObject; + /** + * When this is false, or if the templated value string evaluates to something that is falsy the step will be skipped. + */ if?: string | boolean; } @@ -47,10 +68,28 @@ export interface TaskStep { * @public */ export interface TaskSpecV1beta3 { + /** + * The apiVersion string of the TaskSpec. + */ apiVersion: 'scaffolder.backstage.io/v1beta3'; + /** + * This is a JSONSchema which is used to render a form in the frontend + * to collect user input and validate it against that schema. This can then be used in the `steps` part below to template + * variables passed from the user into each action in the template. + */ parameters: JsonObject; + /** + * A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying + * javascript action and some optional input parameters that may or may not have been collected from the end user. + */ steps: TaskStep[]; + /** + * The output is an object where template authors can pull out information from template actions and return them in a known standard way. + */ output: { [name: string]: JsonValue }; + /** + * Some information about the template that is stored on the task spec. + */ templateInfo?: TemplateInfo; } diff --git a/plugins/scaffolder-common/src/TemplateEntityV1beta3.ts b/plugins/scaffolder-common/src/TemplateEntityV1beta3.ts index 13b699de69..8ded484ee2 100644 --- a/plugins/scaffolder-common/src/TemplateEntityV1beta3.ts +++ b/plugins/scaffolder-common/src/TemplateEntityV1beta3.ts @@ -29,11 +29,32 @@ import schema from './Template.v1beta3.schema.json'; * @public */ export interface TemplateEntityV1beta3 extends Entity { + /** + * The apiVersion string of the TaskSpec. + */ apiVersion: 'scaffolder.backstage.io/v1beta3'; + /** + * The kind of the entity + */ kind: 'Template'; + /** + * The specification of the Template Entity + */ spec: { + /** + * The type that the Template will create. For example service, website or library. + */ type: string; + /** + * This is a JSONSchema or an array of JSONSchema's which is used to render a form in the frontend + * to collect user input and validate it against that schema. This can then be used in the `steps` part below to template + * variables passed from the user into each action in the template. + */ parameters?: JsonObject | JsonObject[]; + /** + * A list of steps to be executed in sequence which are defined by the template. These steps are a list of the underlying + * javascript action and some optional input parameters that may or may not have been collected from the end user. + */ steps: Array<{ id?: string; name?: string; @@ -41,7 +62,13 @@ export interface TemplateEntityV1beta3 extends Entity { input?: JsonObject; if?: string | boolean; }>; + /** + * The output is an object where template authors can pull out information from template actions and return them in a known standard way. + */ output?: { [name: string]: string }; + /** + * The owner entityRef of the TemplateEntity + */ owner?: string; }; }