From dae4f39838c9fa35bd8a6ef2fac91d9f13cc527a Mon Sep 17 00:00:00 2001
From: Himanshu Mishra <himanshu@orkohunter.net>
Date: Sat, 5 Dec 2020 18:36:50 +0100
Subject: [PATCH] techdocs: Add changeset for all three packages

---
 .changeset/friendly-carpets-repeat.md | 45 +++++++++++++++++++++++++++
 .github/styles/vocab.txt              |  1 +
 packages/techdocs-common/README.md    |  4 ++-
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/friendly-carpets-repeat.md

diff --git a/.changeset/friendly-carpets-repeat.md b/.changeset/friendly-carpets-repeat.md
new file mode 100644
index 0000000000000..d42a28a8a616d
--- /dev/null
+++ b/.changeset/friendly-carpets-repeat.md
@@ -0,0 +1,45 @@
+---
+'@backstage/techdocs-common': minor
+'@backstage/plugin-techdocs': minor
+'@backstage/plugin-techdocs-backend': minor
+---
+
+_Breaking changes_
+
+1. Added option to use Google Cloud Storage as a choice to store the static generated files for TechDocs.
+   It can be configured using `techdocs.publisher.type` option in `app-config.yaml`.
+   Step-by-step guide to configure GCS is available here https://backstage.io/docs/features/techdocs/using-cloud-storage
+   Set `techdocs.publisher.type` to `'local'` if you want to continue using local filesystem to store TechDocs files.
+
+2. `techdocs.builder` is now required and can be set to `'local'` or `'ci'`. (Set it to `'local'` for now, since CI/CD build
+   workflow for TechDocs will be available soon (in few weeks)).
+   If builder is set to 'local' and you open a TechDocs page, `techdocs-backend` will try to build the docs, publish to storage and
+   show the generated docs afterwords.
+   If builder is set to `'ci'`, `techdocs-backend` will only fetch the docs and will NOT try to build and publish. In this case of 'ci',
+   we assume that docs are being built in the CI/CD pipeline of the repository.
+   TechDocs will not assume a default value for `techdocs.builder`. It is better to explicitly define it in the `app-config.yaml`.
+
+3. When configuring TechDocs in your backend, there is a difference in how a new publisher is created.
+
+```
+---  const publisher = new LocalPublish(logger, discovery);
++++  const publisher = Publisher.fromConfig(config, logger, discovery);
+```
+
+Based on the config `techdocs.publisher.type`, the publisher could be either Local publisher or Google Cloud Storage publisher.
+
+4. `techdocs.storageUrl` is now a required config. Should be `http://localhost:7000/api/techdocs/static/docs` in most setups.
+
+5. Parts of `@backstage/plugin-techdocs-backend` have been moved to a new package `@backstage/techdocs-common` to build docs. Also to publish docs
+   to-and-fro between TechDocs and a storage (either local or external). However, a Backstage app does NOT need to import the `techdocs-common` package -
+   app should only import `@backstage/plugin-techdocs` and `@backstage/plugin-techdocs-backend`.
+
+_Patch changes_
+
+1. See all of TechDocs config options and its documentation https://backstage.io/docs/features/techdocs/configuration
+
+2. Logic about serving static files and metadata retrieval have been abstracted away from the router in `techdocs-backend` to the instance of publisher.
+
+3. Removed Material UI Spinner from TechDocs header. Spinners cause unnecessary UX distraction.
+   Case 1 (when docs are built and are to be served): Spinners appear for a split second before the name of site shows up. This unnecessarily distracts eyes because spinners increase the size of the Header. A dot (.) would do fine. Definitely more can be done.
+   Case 2 (when docs are being generated): There is already a linear progress bar (which is recommended in Storybook).
diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt
index 7f889392ac410..fa0a0d2087b2d 100644
--- a/.github/styles/vocab.txt
+++ b/.github/styles/vocab.txt
@@ -23,6 +23,7 @@ changesets
 Changesets
 chanwit
 Chanwit
+ci
 cisphobia
 cissexist
 classname
diff --git a/packages/techdocs-common/README.md b/packages/techdocs-common/README.md
index 26e6a8db54f3e..2940df2524360 100644
--- a/packages/techdocs-common/README.md
+++ b/packages/techdocs-common/README.md
@@ -4,6 +4,7 @@ Common functionalities for TechDocs, to be shared between techdocs plugins and t
 
 This package is used by `techdocs-backend` to serve docs from different types of publishers (Google GCS, Local, etc.).
 It is also used to build docs and publish them to storage, by both `techdocs-backend` and `techdocs-cli`.
+
 ## Usage
 
 Create a preparer instance from the [preparers available](/packages/techdocs-common/src/stages/prepare) at which takes an Entity instance.
@@ -11,6 +12,7 @@ Run the [docs generator](/packages/techdocs-common/src/stages/generate) on the p
 Publish the generated directory files to a [storage](/packages/techdocs-common/src/stages/publish) of your choice.
 
 Example:
+
 ```js
 async () => {
   const preparedDir = await preparer.prepare(entity);
@@ -26,7 +28,7 @@ async () => {
     entity: entity,
     directory: resultDir,
   });
-}
+};
 ```
 
 ## Features