Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
techdocs: Add changeset for all three packages
- Loading branch information
1 parent
372160e
commit dae4f39
Showing
3 changed files
with
49 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -23,6 +23,7 @@ changesets | |
Changesets | ||
chanwit | ||
Chanwit | ||
ci | ||
cisphobia | ||
cissexist | ||
classname | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters