Merge branch 'backstage:master' into feat/techdocs-azurite-support
This commit is contained in:
Aswath S
@@ -123,3 +123,14 @@ source that should be mirrored into Backstage. To make Backstage a mirror of
|
||||
this remote source, users cannot also register new entities with e.g. the
|
||||
[catalog-import](https://github.com/backstage/backstage/tree/master/plugins/catalog-import)
|
||||
plugin.
|
||||
|
||||
## Clean up orphaned entities
|
||||
|
||||
In short entities can become orphaned through multiple means, such as when a catalog-info YAML file is moved from one place to another in the version control system without updating the registration in the catalog. For safety reasons the default behavior is to just tag the orphaned entities, and keep them around. You can read more about orphaned entities [here](life-of-an-entity.md#orphaning).
|
||||
|
||||
However, if you do with to automatically remove the orphaned entities, you can use the following configuration, and everything with an orphaned entity tag will be eventually deleted.
|
||||
|
||||
```
|
||||
catalog:
|
||||
orphanStrategy: delete
|
||||
```
|
||||
|
||||
@@ -222,7 +222,8 @@ either, it becomes _orphaned_. The end result is as follows:
|
||||
- The stitching process injects a `backstage.io/orphan: 'true'` annotation on
|
||||
the child entity.
|
||||
- The child entity is _not_ removed from the catalog, but stays around until
|
||||
explicitly deleted via the catalog API, or "reclaimed" by the original parent
|
||||
explicitly deleted via the catalog API, implicitly if `orphanStrategy: delete`
|
||||
configuration is set, or until it is "reclaimed" by the original parent
|
||||
or another parent starting to reference it.
|
||||
- The catalog page in Backstage for the child entity detects the new annotation
|
||||
and informs users about the orphan status.
|
||||
@@ -259,9 +260,13 @@ entities without explicit owner consent. The catalog therefore takes the stance
|
||||
that entities that often were added by direct user action should also be deleted
|
||||
only by direct user action.
|
||||
|
||||
It is possible to use the catalog API to build automated "reaper" systems that
|
||||
finally delete entities that are orphaned. This is however not something that's
|
||||
provided out of the box.
|
||||
However, if you want to delete orphaned entities automatically anyway, you can
|
||||
enable the automated clean up with the following app-config option.
|
||||
|
||||
```
|
||||
catalog:
|
||||
orphanStrategy: delete
|
||||
```
|
||||
|
||||
## Implicit Deletion
|
||||
|
||||
|
||||
@@ -122,12 +122,12 @@ page header, TechDocs Addons whose location is `Header` will not be rendered.
|
||||
Addons can, in principle, be provided by any plugin! To make it easier to
|
||||
discover available Addons, we've compiled a list of them here:
|
||||
|
||||
| Addon | Package/Plugin | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [`<ExpandableNavigation />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. |
|
||||
| [`<ReportIssue />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. |
|
||||
| [`<TextSize />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. |
|
||||
| [`<LightBox />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. |
|
||||
| Addon | Package/Plugin | Description |
|
||||
| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [`<ExpandableNavigation />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.expandablenavigation) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to expand or collapse the entire TechDocs main navigation, and keeps the user's preferred state between documentation sites. |
|
||||
| [`<ReportIssue />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.reportissue) | `@backstage/plugin-techdocs-module-addons-contrib` | Allows TechDocs users to select a portion of text on a TechDocs page and open an issue against the repository that contains the documentation, populating the issue description with the selected text according to a configurable template. |
|
||||
| [`<TextSize />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.textsize) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to customize text size on documentation pages, they can select how much they want to increase or decrease the font size via slider or buttons. The default value for font size is 100% and this setting is kept in the browser's local storage whenever it is changed. |
|
||||
| [`<LightBox />`](https://backstage.io/docs/reference/plugin-techdocs-module-addons-contrib.lightbox) | `@backstage/plugin-techdocs-module-addons-contrib` | This TechDocs addon allows users to open images in a light-box on documentation pages, they can navigate between images if there are several on one page. The image size of the light-box image is the same as the image size on the document page. When clicking on the zoom icon it zooms the image to fit in the screen (similar to `background-size: contain`). |
|
||||
|
||||
Got an Addon to contribute? Feel free to add a row above!
|
||||
|
||||
|
||||
@@ -141,6 +141,7 @@ Options:
|
||||
if not found.
|
||||
--etag <ETAG> A unique identifier for the prepared tree e.g. commit SHA. If provided it will be stored
|
||||
in techdocs_metadata.json.
|
||||
--defaultPlugin <PLUGIN_NAME> Plugins which should be added automatically to the mkdocs.yaml file. (default: [])
|
||||
--omitTechdocsCoreMkdocsPlugin An option to disable automatic addition of techdocs-core plugin to the mkdocs.yaml files.
|
||||
Defaults to false, which means that the techdocs-core plugin is always added to the mkdocs file.
|
||||
--legacyCopyReadmeMdToIndexMd Attempt to ensure an index.md exists falling back to using <docs-dir>/README.md or README.md
|
||||
|
||||
@@ -49,6 +49,15 @@ techdocs:
|
||||
# will be broken in these scenarios.
|
||||
legacyCopyReadmeMdToIndexMd: false
|
||||
|
||||
# (Optional) Configures the default plugins which should be added
|
||||
# automatically to every mkdocs.yaml file. This simplifies the usage as
|
||||
# e.g. styling plugins can be added once for all.
|
||||
# Make sure that the defined plugins are installed locally / in the Docker
|
||||
# image.
|
||||
# By default, only the techdocs-core plugin will be added (except if
|
||||
# omitTechdocsCorePlugin: true).
|
||||
defaultPlugins: ['techdocs-core']
|
||||
|
||||
# techdocs.builder can be either 'local' or 'external'.
|
||||
# Using the default build strategy, if builder is set to 'local' and you open a TechDocs page,
|
||||
# techdocs-backend will try to generate the docs, publish to storage and show the generated docs afterwards.
|
||||
|
||||
@@ -13,6 +13,34 @@ npm.
|
||||
Releases are handled by changesets and trigger whenever the "Version Packages"
|
||||
PR is merged. This is typically done every Tuesday around noon CET.
|
||||
|
||||
## Next Line Release Process
|
||||
|
||||
- PR Checks: Ensure there are no outstanding PRs pending to be merged for this version. If there are any, reach out to maintainers and relevant owners of the affected code reminding them of the deadline for the release.
|
||||
- [optional] Lock main branch
|
||||
- Lock the main branch to prevent any new merges.
|
||||
- Note: Admin rights are required to lock the branch. If you lack the necessary permissions, contact a core maintainer to perform this action on your behalf.
|
||||
- Check [`Version Packages (next)` Pull Request](https://github.com/backstage/backstage/pulls?q=is%3Aopen+is%3Apr+in%3Atitle+%22Version+Packages+%28next%29%22)
|
||||
- Verify the version we are shipping is correct, by looking at the version packages PR title. It should be "Version Packages (next)"
|
||||
- Check [`.changeset/pre.json`](https://github.com/backstage/backstage/blob/master/.changeset/pre.json) if the `mode` is set to `pre`. If you encounter `mode: "exit"` or if it's not defined, it indicates a mainline release.
|
||||
- Verify that there are no active/unfinished `sync_version-packages` actions running (https://github.com/backstage/backstage/actions/workflows/sync_version-packages.yml)
|
||||
- Locking the main branch will prevent new ones to be created, but be sure to check for running actions again after unlocking, since it may cause pending auto-merge PRs to be merged.
|
||||
- Check [`Version Packages (next)` Pull Request](https://github.com/backstage/backstage/pulls?q=is%3Aopen+is%3Apr+in%3Atitle+%22Version+Packages+%28next%29%22) for sufficient approval to be merged
|
||||
- Check generated `changelog` in the changed files of the pull request under `docs/releases` to see if there are any unexpected major bumps e.g. by searching the file
|
||||
- Review & approve changes
|
||||
- Reach out to core maintainer to merge the pull request
|
||||
- Heads-up: The microsite building step can be skipped as long as the `prettier` task passes & everything else looks green
|
||||
|
||||
Merging the `Version Packages (next)` Pull Request will trigger the deployment workflows. Follow along the [deployment workflow](https://github.com/backstage/backstage/actions/workflows/deploy_packages.yml). If you notice flakiness (e.g. if the build is flaky or if the release step runs into an error with releasing to npm) just restart the workflow.
|
||||
|
||||
Congratulations on the release! There should be now a post in the [`#announcements` channel](https://discord.com/channels/687207715902193673/705123584468582400) in Discord linking to the release tag - check if links & tag look as expected. Finally unlock the main branch again. Merging PRs in master directly after release should be done with caution as it potential complicates fixing issues introduced in the release.
|
||||
|
||||
## Switching Release Modes
|
||||
|
||||
- To enter pre-release mode: `yarn changeset pre enter next` & create PR + merge changes
|
||||
- To exit pre-release mode: `yarn changeset pre exit` & create PR + merge changes
|
||||
- Has to be done before the mainline release
|
||||
- It's not time critical; Affects the next release happening
|
||||
|
||||
## Emergency Release Process
|
||||
|
||||
**This emergency release process is intended only for the Backstage
|
||||
|
||||
Reference in New Issue
Block a user