docs(techdocs-common): add case sentitive migration steps

Co-authored-by: Eric Peterson <ericpeterson@spotify.com>
Signed-off-by: Camila Belo <camilaibs@gmail.com>

.changeset/techdocs-all-done.md

@@ -1,7 +1,19 @@
 ---
-'@backstage/plugin-techdocs': patch
+'@backstage/plugin-techdocs': minor
+'@backstage/plugin-techdocs-backend': minor
+'@backstage/techdocs-common': minor
 ---
 
+TechDocs sites can now be accessed using paths containing entity triplets of
+any case (e.g. `/docs/namespace/KIND/name` or `/docs/namespace/kind/name`).
+
+If you do not use an external storage provider for serving TechDocs, this is a
+transparent change and no action is required from you.
+
+If you _do_ use an external storage provider for serving TechDocs (e.g. Google
+Cloud Storage, AWS S3, or Azure Blob Storage), you must run a migration command
+against your storage provider before updating to this version.
+
+[A migration guide is available here](#todo).
+
 This is the third and final step of migrating cloud storage entities to lowercase ([see](https://github.com/backstage/backstage/issues/4367#issuecomment-876461002)).
-
-Updates GCS, AWS S3 and Azure Blob Storage Provider to lowercase entity triplet paths before reading and writing to it cloud storage.

docs/features/techdocs/configuration.md

@@ -113,6 +113,14 @@ techdocs:
         # https://docs.microsoft.com/en-us/azure/storage/common/storage-auth?toc=/azure/storage/blobs/toc.json
         accountKey: ${TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY}
 
+  # (Optional and not recommended) Prior to version [0.x.y] of TechDocs, docs
+  # sites could only be accessed over paths with case-sensitive entity triplets
+  # e.g. (namespace/Kind/name). If you are upgrading from an older version of
+  # TechDocs and are unable to perform the necessary migration of files in your
+  # external storage, you can set this value to `true` to temporarily revert to
+  # the old, case-sensitive entity triplet behavior.
+  legacyUseCaseSensitiveTripletPaths: false
+
   # (Optional and Legacy) TechDocs makes API calls to techdocs-backend using this URL. e.g. get docs of an entity, get metadata, etc.
   # You don't have to specify this anymore.
 

docs/features/techdocs/how-to-guides.md

@@ -184,3 +184,73 @@ annotation ) as an 'entities' attribute.
 
 For a reference to the React structure of the default home page, please refer to
 `plugins/techdocs/src/home/components/TechDocsCustomHome.tsx`.
+
+## How to migrate from TechDocs Alpha to Beta
+
+> This guide only applies to the "recommended" TechDocs deployment method (where
+> an external storage provider and external CI/CD is used). If you use the
+> "basic" or "out-of-the-box" setup, you can stop here! No action needed.
+
+The beta version of TechDocs (v0.x.y) made a breaking change to the way TechDocs
+content was accessed and stored, allowing pages to be accessed with
+case-insensitive entity triplet paths (e.g. `/docs/namespace/kind/name` whereas
+in prior versions, they could only be accessed at `/docs/namespace/Kind/name`).
+In order to enable this change, documentation has be stored in an external
+storage provider using an object key whose entity triplet is lower-cased.
+
+New installations of TechDocs since the beta version will work fine with no
+action, but for those who were running TechDocs prior to this version, a
+migration will need to be performed so that all existing content in your storage
+bucket matches this lower-case entity triplet expectation.
+
+1. **Ensure you have the right permissions on your storage provider**: In order
+   to migrate files in your storage provider, the `techdocs-cli` needs to be
+   able to read/copy/rename/move/delete files. The exact instructions vary by
+   storage provider, but check the [using cloud storage][using-cloud-storage]
+   page for details.
+
+2. **Run a non-destructive migration of files**: Ensure you have the latest
+   version of `techdocs-cli` installed. Then run the following command, using
+   the details relevant for your provider / configuration. This will copy all
+   files from, e.g. `namespace/Kind/name/index.html` to
+   `namespace/kind/name/index.html`, without removing the original files.
+
+```sh
+techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --verbose
+```
+
+3. **Deploy the updated versions of the TechDocs plugins**: Once the migration
+   above has been run, you can deploy the beta versions of the TechDocs backend
+   and frontend plugins to your Backstage instance.
+
+4. **Verify that your TechDocs sites are still loading/accessible**: Try
+   accessing a TechDocs site using different entity-triplet case variants, e.g.
+   `/docs/namespace/KIND/name` or `/docs/namespace/kind/name`. Your TechDocs
+   site should load regardless of the URL path casing you use.
+
+5. **Clean up the old objects from storage**: Once you've verified that your
+   TechDocs site is accessible, you can clean up your storage bucket by
+   re-running the `migrate` command on the TechDocs CLI, but with an additional
+   `removeOriginal` flag passed:
+
+```sh
+techdocs-cli migrate --publisher-type <awsS3|googleGcs|azureBlobStorage> --storage-name <bucket/container name> --removeOriginal --verbose
+```
+
+6. **Update your CI/CD pipelines to use the beta version of the TechDocs CLI**:
+   Finally, you can update all of your CI/CD pipelines to use at least v0.x.y of
+   the TechDocs CLI, ensuring that all sites are published to the new,
+   lower-cased entity triplet paths going forward.
+
+If you encounter problems running this migration, please [report the
+issue][beta-migrate-bug]. You can temporarily revert to pre-beta storage
+expectations with a configuration change:
+
+```yaml
+techdocs:
+  legacyUseCaseSensitiveTripletPaths: true
+```
+
+[beta-migrate-bug]:
+https://github.com/backstage/backstage/issues/new?assignees=&labels=bug&template=bug_template.md&title=[TechDocs]%20Unable%20to%20run%20beta%20migration
+[using-cloud-storage]: ./using-cloud-storage.md

plugins/techdocs-backend/config.d.ts

@@ -248,7 +248,12 @@ export interface Config {
     storageUrl?: string;
 
     /**
-     * (Optional)
+     * (Optional and not recommended) Prior to version [0.x.y] of TechDocs, docs
+     * sites could only be accessed over paths with case-sensitive entity triplets
+     * e.g. (namespace/Kind/name). If you are upgrading from an older version of
+     * TechDocs and are unable to perform the necessary migration of files in your
+     * external storage, you can set this value to `true` to temporarily revert to
+     * the old, case-sensitive entity triplet behavior.
      */
     legacyUseCaseSensitiveTripletPaths?: boolean;
   };