TechDocs: Warn when using legacy git preparer and dir preparer in backstage.io/techdocs-ref

Context: https://github.com/backstage/backstage/issues/4409

packages/techdocs-common/src/stages/prepare/commonGit.ts

@@ -39,6 +39,12 @@ export class CommonGitPreparer implements PreparerBase {
     entity: Entity,
     options?: { etag?: string },
   ): Promise<PreparerResponse> {
+    this.logger.warn(
+      'You are using the legacy git preparer in TechDocs which will be removed in near future (30 days). ' +
+        'Migrate to URL reader by updating `backstage.io/techdocs-ref` annotation in `catalog-info.yaml` ' +
+        'to be prefixed with `url:`. Read the migration guide and benefits at https://github.com/backstage/backstage/issues/4409 ',
+    );
+
     const { target } = parseReferenceAnnotation(
       'backstage.io/techdocs-ref',
       entity,

packages/techdocs-common/src/stages/prepare/dir.ts

@@ -69,6 +69,12 @@ export class DirectoryPreparer implements PreparerBase {
   }
 
   async prepare(entity: Entity): Promise<PreparerResponse> {
+    this.logger.warn(
+      'You are using the legacy dir preparer in TechDocs which will be removed in near future (30 days). ' +
+        'Migrate to URL reader by updating `backstage.io/techdocs-ref` annotation in `catalog-info.yaml` ' +
+        'to be prefixed with `url:`. Read the migration guide and benefits at https://github.com/backstage/backstage/issues/4409 ',
+    );
+
     const { target } = parseReferenceAnnotation(
       'backstage.io/techdocs-ref',
       entity,

plugins/techdocs-backend/src/DocsBuilder/builder.ts

@@ -76,6 +76,10 @@ export class DocsBuilder {
       );
     }
 
+    /**
+     * Prepare and cache check
+     */
+
     // Use the in-memory storage for setting and getting etag for this entity.
     const buildMetadataStorage = new BuildMetadataStorage(
       this.entity.metadata.uid,
@@ -103,6 +107,11 @@ export class DocsBuilder {
       `TechDocs prepare step completed for entity ${getEntityId(this.entity)}.`,
     );
     this.logger.debug(`Prepared files temporarily stored at ${preparedDir}`);
+
+    /**
+     * Generate
+     */
+
     this.logger.info(`Running generator on entity ${getEntityId(this.entity)}`);
     // Create a temporary directory to store the generated files in.
     const tmpdirPath = os.tmpdir();
@@ -111,7 +120,6 @@ export class DocsBuilder {
     const outputDir = await fs.mkdtemp(
       path.join(tmpdirResolvedPath, 'techdocs-tmp-'),
     );
-
     const parsedLocationAnnotation = getLocationForEntity(this.entity);
     await this.generator.run({
       inputDir: preparedDir,
@@ -121,9 +129,9 @@ export class DocsBuilder {
     });
 
     this.logger.debug(`Generated files temporarily stored at ${outputDir}`);
-    // Remove Prepared directory
-    // Can not remove prepared directory in case of git preparer since the local git repository
-    // is used to get etag on subsequent requests.
+    // Remove Prepared directory since it is no longer needed.
+    // Caveat: Can not remove prepared directory in case of git preparer since the
+    // local git repository is used to get etag on subsequent requests.
     if (this.preparer instanceof UrlPreparer) {
       this.logger.debug(
         `Removing prepared directory ${preparedDir} since the site has been generated.`,
@@ -136,6 +144,10 @@ export class DocsBuilder {
       }
     }
 
+    /**
+     * Publish
+     */
+
     this.logger.info(`Running publisher on entity ${getEntityId(this.entity)}`);
     await this.publisher.publish({
       entity: this.entity,