Merge branch 'master' of https://github.com/backstage/backstage into bazaar-columns

.changeset/mean-cars-wash.md

@@ -0,0 +1,5 @@
+---
+'@backstage/catalog-client': patch
+---
+
+Improved API documentation for catalog-client.

.changeset/nine-dots-suffer.md

@@ -0,0 +1,14 @@
+---
+'@backstage/create-app': patch
+---
+
+Updated the app template to no longer include the `--no-private` flag for the `create-plugin` command.
+
+To apply this change to an existing application, remove the `--no-private` flag from the `create-plugin` command in the root `package.json`:
+
+```diff
+   "prettier:check": "prettier --check .",
+-  "create-plugin": "backstage-cli create-plugin --scope internal --no-private",
++  "create-plugin": "backstage-cli create-plugin --scope internal",
+   "remove-plugin": "backstage-cli remove-plugin"
+```

docs/features/software-templates/migrating-from-v1beta2-to-v1beta3.md

@@ -125,8 +125,8 @@ input schema.
         input:
 -         address: '{{ json parameters.address }}'
 +         address: ${{ parameters.address }}
--         number: '{{ parameters.number }}'
-+         number: ${{ parameters.number }} # this will now make sure that the type of number is a number 🙏
+-         test: '{{ parameters.test }}'
++         test: ${{ parameters.test }} # this will now make sure that the type of test is a number 🙏
 ```
 
 ## `parseRepoUrl` is now a `filter`

packages/catalog-client/api-report.md

@@ -7,7 +7,7 @@ import { Entity } from '@backstage/catalog-model';
 import { EntityName } from '@backstage/catalog-model';
 import { Location as Location_2 } from '@backstage/catalog-model';
 
-// @public (undocumented)
+// @public
 export type AddLocationRequest = {
   type?: string;
   target: string;
@@ -15,126 +15,106 @@ export type AddLocationRequest = {
   presence?: 'optional' | 'required';
 };
 
-// @public (undocumented)
+// @public
 export type AddLocationResponse = {
   location: Location_2;
   entities: Entity[];
   exists?: boolean;
 };
 
-// @public (undocumented)
+// @public
 export const CATALOG_FILTER_EXISTS: unique symbol;
 
-// @public (undocumented)
+// @public
 export interface CatalogApi {
-  // (undocumented)
   addLocation(
     location: AddLocationRequest,
     options?: CatalogRequestOptions,
   ): Promise<AddLocationResponse>;
-  // (undocumented)
   getEntities(
     request?: CatalogEntitiesRequest,
     options?: CatalogRequestOptions,
   ): Promise<CatalogListResponse<Entity>>;
-  // (undocumented)
   getEntityAncestors(
     request: CatalogEntityAncestorsRequest,
     options?: CatalogRequestOptions,
   ): Promise<CatalogEntityAncestorsResponse>;
-  // (undocumented)
   getEntityByName(
     name: EntityName,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
-  // (undocumented)
   getLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  // (undocumented)
   getLocationById(
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  // (undocumented)
   getOriginLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  // (undocumented)
   refreshEntity(
     entityRef: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
-  // (undocumented)
   removeEntityByUid(
     uid: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
-  // (undocumented)
   removeLocationById(
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
 }
 
-// @public (undocumented)
+// @public
 export class CatalogClient implements CatalogApi {
   constructor(options: { discoveryApi: DiscoveryApi });
-  // (undocumented)
   addLocation(
     { type, target, dryRun, presence }: AddLocationRequest,
     options?: CatalogRequestOptions,
   ): Promise<AddLocationResponse>;
-  // (undocumented)
   getEntities(
     request?: CatalogEntitiesRequest,
     options?: CatalogRequestOptions,
   ): Promise<CatalogListResponse<Entity>>;
-  // (undocumented)
   getEntityAncestors(
     request: CatalogEntityAncestorsRequest,
     options?: CatalogRequestOptions,
   ): Promise<CatalogEntityAncestorsResponse>;
-  // (undocumented)
   getEntityByName(
     compoundName: EntityName,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
-  // (undocumented)
   getLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  // (undocumented)
   getLocationById(
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  // (undocumented)
   getOriginLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
   ): Promise<Location_2 | undefined>;
-  // (undocumented)
   refreshEntity(
     entityRef: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
-  // (undocumented)
   removeEntityByUid(
     uid: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
-  // (undocumented)
   removeLocationById(
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
 }
 
-// @public (undocumented)
+// @public
 export type CatalogEntitiesRequest = {
   filter?:
     | Record<string, string | symbol | (string | symbol)[]>[]
@@ -143,12 +123,12 @@ export type CatalogEntitiesRequest = {
   fields?: string[] | undefined;
 };
 
-// @public (undocumented)
+// @public
 export type CatalogEntityAncestorsRequest = {
   entityRef: string;
 };
 
-// @public (undocumented)
+// @public
 export type CatalogEntityAncestorsResponse = {
   root: EntityName;
   items: {
@@ -157,12 +137,12 @@ export type CatalogEntityAncestorsResponse = {
   }[];
 };
 
-// @public (undocumented)
+// @public
 export type CatalogListResponse<T> = {
   items: T[];
 };
 
-// @public (undocumented)
+// @public
 export type CatalogRequestOptions = {
   token?: string;
 };

packages/catalog-client/src/CatalogClient.ts

@@ -39,7 +39,11 @@ import {
 } from './types/api';
 import { DiscoveryApi } from './types/discovery';
 
-/** @public */
+/**
+ * A frontend and backend compatible client for communicating with the Backstage Catalog.
+ *
+ * @public
+ * */
 export class CatalogClient implements CatalogApi {
   private readonly discoveryApi: DiscoveryApi;
 
@@ -47,6 +51,16 @@ export class CatalogClient implements CatalogApi {
     this.discoveryApi = options.discoveryApi;
   }
 
+  /**
+   * Gets the Ancestors of an Entity.
+   *
+   * @param request - A request type for retrieving Entity ancestors.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A CatalogEntityAncestorsResponse.
+   *
+   * @public
+   */
   async getEntityAncestors(
     request: CatalogEntityAncestorsRequest,
     options?: CatalogRequestOptions,
@@ -61,6 +75,16 @@ export class CatalogClient implements CatalogApi {
     );
   }
 
+  /**
+   * Gets a Location by Id.
+   *
+   * @param id - A string containing the Id.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A {@link catalog-model#Location_2}.
+   *
+   * @public
+   */
   async getLocationById(
     id: string,
     options?: CatalogRequestOptions,
@@ -72,6 +96,16 @@ export class CatalogClient implements CatalogApi {
     );
   }
 
+  /**
+   * Gets a set of Entities.
+   *
+   * @param request - A request type for retrieving an Entity.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A CatalogListResponse.
+   *
+   * @public
+   */
   async getEntities(
     request?: CatalogEntitiesRequest,
     options?: CatalogRequestOptions,
@@ -139,6 +173,16 @@ export class CatalogClient implements CatalogApi {
     return { items: entities.sort(refCompare) };
   }
 
+  /**
+   * Gets a given Entity based on a provided name.
+   *
+   * @param compoundName - A string containing the name.
+   * @param options - An object with your preferred options.
+   *
+   * @returns An {@link catalog-model#Entity}.
+   *
+   * @public
+   */
   async getEntityByName(
     compoundName: EntityName,
     options?: CatalogRequestOptions,
@@ -153,6 +197,14 @@ export class CatalogClient implements CatalogApi {
     );
   }
 
+  /**
+   * Refreshes an Entity.
+   *
+   * @param entityRef - A string containing the entityREf
+   * @param options - An object with your preferred options.
+   *
+   * @public
+   */
   async refreshEntity(entityRef: string, options?: CatalogRequestOptions) {
     const response = await fetch(
       `${await this.discoveryApi.getBaseUrl('catalog')}/refresh`,
@@ -171,6 +223,16 @@ export class CatalogClient implements CatalogApi {
     }
   }
 
+  /**
+   * Adds a location.
+   *
+   * @param options - An object with your preferred options.
+   * @param AddLocationRequest - A request object for adding locations.
+   *
+   * @returns An AddLocationResponse
+   *
+   * @public
+   */
   async addLocation(
     { type = 'url', target, dryRun, presence }: AddLocationRequest,
     options?: CatalogRequestOptions,
@@ -206,6 +268,16 @@ export class CatalogClient implements CatalogApi {
     };
   }
 
+  /**
+   *  Gets an origin Location By Entity.
+   *
+   * @param entity - An Entity
+   * @param options - An object with your preferred options.
+   *
+   * @returns A {@link catalog-model#Location_2}.
+   *
+   * @public
+   */
   async getOriginLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
@@ -225,6 +297,16 @@ export class CatalogClient implements CatalogApi {
       .find(l => locationCompound === stringifyLocationReference(l));
   }
 
+  /**
+   * Gets a Location by Entity.
+   *
+   * @param entity - An Entity
+   * @param options - An object with your preferred options.
+   *
+   * @returns A {@link catalog-model#Location_2}.
+   *
+   * @public
+   */
   async getLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
@@ -243,6 +325,14 @@ export class CatalogClient implements CatalogApi {
       .find(l => locationCompound === stringifyLocationReference(l));
   }
 
+  /**
+   * Removes a location as identified by Id.
+   *
+   * @param id - A string containing the Id
+   * @param options - An object with your preferred options.
+   *
+   * @public
+   */
   async removeLocationById(
     id: string,
     options?: CatalogRequestOptions,
@@ -254,6 +344,14 @@ export class CatalogClient implements CatalogApi {
     );
   }
 
+  /**
+   * Removes an Entity as identified by Uid.
+   *
+   * @param uid - A string containing the Uid
+   * @param options - An object with your preferred options.
+   *
+   * @public
+   */
   async removeEntityByUid(
     uid: string,
     options?: CatalogRequestOptions,

packages/catalog-client/src/types/api.ts

@@ -16,10 +16,18 @@
 
 import { Entity, EntityName, Location } from '@backstage/catalog-model';
 
-/** @public */
+/**
+ * A Symbol to define if a catalog filter exists or not.
+ *
+ * @public
+ */
 export const CATALOG_FILTER_EXISTS = Symbol('CATALOG_FILTER_EXISTS');
 
-/** @public */
+/**
+ * A request type for retrieving catalog Entities.
+ *
+ * @public
+ */
 export type CatalogEntitiesRequest = {
   filter?:
     | Record<string, string | symbol | (string | symbol)[]>[]
@@ -28,75 +36,176 @@ export type CatalogEntitiesRequest = {
   fields?: string[] | undefined;
 };
 
-/** @public */
+/**
+ * A request type for Catalog Entity Ancestor information.
+ *
+ * @public
+ */
 export type CatalogEntityAncestorsRequest = {
   entityRef: string;
 };
 
-/** @public */
+/**
+ * A response type for Catalog Entity Ancestor information.
+ *
+ * @public
+ */
 export type CatalogEntityAncestorsResponse = {
   root: EntityName;
   items: { entity: Entity; parents: EntityName[] }[];
 };
 
-/** @public */
+/**
+ * A response type for the result of a catalog operation in list form.
+ *
+ * @public
+ */
 export type CatalogListResponse<T> = {
   items: T[];
 };
 
-/** @public */
+/**
+ * Options you can pass into a catalog request for additional information.
+ *
+ * @public
+ */
 export type CatalogRequestOptions = {
   token?: string;
 };
 
-/** @public */
+/**
+ * Public functions for interacting with the Catalog API.
+ *
+ * @public
+ */
 export interface CatalogApi {
-  // Entities
+  /**
+   * Gets the Entities from the catalog based on your request and options.
+   *
+   * @param request - An object with your filters and fields.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A CatalogListResponse with items typed Catalog Model Entity.
+   *
+   */
   getEntities(
     request?: CatalogEntitiesRequest,
     options?: CatalogRequestOptions,
   ): Promise<CatalogListResponse<Entity>>;
+  /**
+   * Gets the Entity ancestor information from the catalog based on your request and options.
+   *
+   * @param request - An object with your filters and fields.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A CatalogEntityAncestorsResponse.
+   */
   getEntityAncestors(
     request: CatalogEntityAncestorsRequest,
     options?: CatalogRequestOptions,
   ): Promise<CatalogEntityAncestorsResponse>;
+  /**
+   * Gets a single Entity from the catalog by Entity name.
+   *
+   * @param name - A complete Entity name, with the full kind-namespace-name triplet.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A {@link catalog-model#Entity}.
+   */
   getEntityByName(
     name: EntityName,
     options?: CatalogRequestOptions,
   ): Promise<Entity | undefined>;
+  /**
+   * Removes a single Entity from the catalog by Entity UID.
+   *
+   * @param uid - A string of the Entity UID.
+   * @param options - An object with your preferred options.
+   *
+   */
   removeEntityByUid(
     uid: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
+  /**
+   * Refreshes an Entity in the catalog.
+   *
+   * @param entityRef - A string in the form of 'Kind/default:foo'.
+   * @param options - An object with your preferred options.
+   *
+   */
   refreshEntity(
     entityRef: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
 
   // Locations
+  /**
+   * Gets a Location object by ID from the catalog.
+   *
+   * @param id - A string in of the Location Id.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A {@link catalog-model#Location_2}.
+   */
   getLocationById(
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<Location | undefined>;
+  /**
+   * Gets origin location by Entity.
+   *
+   * @param entity - An {@link catalog-model#Entity}.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A {@link catalog-model#Location_2}.
+   */
   getOriginLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
   ): Promise<Location | undefined>;
+  /**
+   * Gets Location by Entity.
+   *
+   * @param entity - An {@link catalog-model#Entity}.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A {@link catalog-model#Location_2}.
+   */
   getLocationByEntity(
     entity: Entity,
     options?: CatalogRequestOptions,
   ): Promise<Location | undefined>;
+  /**
+   * Adds a Location.
+   *
+   * @param location - A request type for adding a Location to the catalog.
+   * @param options - An object with your preferred options.
+   *
+   * @returns A AddLocationResponse.
+   */
   addLocation(
     location: AddLocationRequest,
     options?: CatalogRequestOptions,
   ): Promise<AddLocationResponse>;
+  /**
+   * Removes a Location by Id.
+   *
+   * @param id - A string in of the Location Id.
+   * @param options - An object with your preferred options.
+   *
+   */
   removeLocationById(
     id: string,
     options?: CatalogRequestOptions,
   ): Promise<void>;
 }
 
-/** @public */
+/**
+ * A request type for adding a Location to the catalog.
+ *
+ * @public
+ */
 export type AddLocationRequest = {
   type?: string;
   target: string;
@@ -104,7 +213,11 @@ export type AddLocationRequest = {
   presence?: 'optional' | 'required';
 };
 
-/** @public */
+/**
+ * A response type for adding a Location to the catalog.
+ *
+ * @public
+ */
 export type AddLocationResponse = {
   location: Location;
   entities: Entity[];

packages/create-app/templates/default-app/package.json.hbs

@@ -20,7 +20,7 @@
     "lint": "lerna run lint --since origin/master --",
     "lint:all": "lerna run lint --",
     "prettier:check": "prettier --check .",
-    "create-plugin": "backstage-cli create-plugin --scope internal --no-private",
+    "create-plugin": "backstage-cli create-plugin --scope internal",
     "remove-plugin": "backstage-cli remove-plugin"
   },
   "resolutions": {