Merge branch 'master' of github.com:spotify/backstage into shmidt-i/circle-ci-plugin-new-route-api

2020-09-07 22:15:12 +02:00
parent b9c523f3f5 2db299cbcb
commit f3acee2537
187 changed files with 9837 additions and 3115 deletions
@@ -71,10 +71,9 @@ import {
  AlertApiForwarder,
  ErrorApiForwarder,
  ErrorAlerter,
-  ConfigApi
+  ConfigApi,
 } from '@backstage/core';

-
 const apis = (config: ConfigApi) => {
  const builder = ApiRegistry.builder();

@@ -84,7 +83,7 @@ const apis = (config: ConfigApi) => {
  // The error API uses the alert API to send error notifications to the user.
  builder.add(errorApiRef, new ErrorAlerter(alertApi, new ErrorApiForwarder()));
  return builder.build();
-}
+};

 const app = createApp({
  apis,
@@ -116,8 +116,8 @@ components. If you’d like to help build up our design system, you can also add
 components we’ve designed to the Storybook as well.

 **[Figma](https://www.figma.com/@backstage)** - we're stoked to be using Figma
-Community to share our design assets. You can duplicate our UI Kit
-and design your own plugin for Backstage.
+Community to share our design assets. You can duplicate our UI Kit and design
+your own plugin for Backstage.

 **[Discord](https://discord.gg/EBHEGzX)** - all design questions should be
 directed to the _#design_ channel.
@@ -235,6 +235,9 @@ The `backstage.io/` prefix is reserved for use by Backstage core components.

 Values can be of any length, but are limited to being strings.

+There is a list of [well-known annotations](well-known-annotations.md), but
+anybody is free to add more annotations as they see fit.
+
 ### `tags` [optional]

 A list of single-valued strings, for example to classify catalog entities in
@@ -290,7 +293,7 @@ Exactly equal to `backstage.io/v1alpha1` and `Component`, respectively.

 The type of component as a string, e.g. `website`. This field is required.

-The software catalog accepts any type value, but an organisation should take
+The software catalog accepts any type value, but an organization should take
 great care to establish a proper taxonomy for these. Tools including Backstage
 itself may read this field and behave differently depending on its value. For
 example, a website type component may present tooling in the Backstage interface
@@ -304,9 +307,9 @@ The current set of well-known and common values for this field is:

 ### `spec.lifecycle` [required]

-The lifecyle state of the component, e.g. `production`. This field is required.
+The lifecycle state of the component, e.g. `production`. This field is required.

-The software catalog accepts any lifecycle value, but an organisation should
+The software catalog accepts any lifecycle value, but an organization should
 take great care to establish a proper taxonomy for these.

 The current set of well-known and common values for this field is:
@@ -418,7 +421,7 @@ potentially search and group templates by these tags.
 The type of component as a string, e.g. `website`. This field is optional but
 recommended.

-The software catalog accepts any type value, but an organisation should take
+The software catalog accepts any type value, but an organization should take
 great care to establish a proper taxonomy for these. Tools including Backstage
 itself may read this field and behave differently depending on its value. For
 example, a website type component may present tooling in the Backstage interface
@@ -508,7 +511,7 @@ Exactly equal to `backstage.io/v1alpha1` and `API`, respectively.
 The type of the API definition as a string, e.g. `openapi`. This field is
 required.

-The software catalog accepts any type value, but an organisation should take
+The software catalog accepts any type value, but an organization should take
 great care to establish a proper taxonomy for these. Tools including Backstage
 itself may read this field and behave differently depending on its value. For
 example, an OpenAPI type API may be displayed using an OpenAPI viewer tooling in
@@ -1,7 +1,7 @@
 ---
 id: software-catalog-overview
 title: Backstage Service Catalog (alpha)
-sidebar_label: Backstage Service Catalog
+sidebar_label: Overview
 ---

 ## What is a Service Catalog?
@@ -48,7 +48,7 @@ There are 3 ways to add components to the catalog:

 1. Manually register components
 2. Creating new components through Backstage
-3. Integrating with and [external source](external-integrations.md)
+3. Integrating with an [external source](external-integrations.md)

 ### Manually register components

@@ -0,0 +1,134 @@
+---
+id: well-known-annotations
+title: Well-known Annotations on Catalog Entities
+sidebar_label: Well-known Annotations
+---
+
+This section lists a number of well known
+[annotations](descriptor-format.md#annotations-optional), that have defined
+semantics. They can be attached to catalog entities and consumed by plugins as
+needed.
+
+## Annotations
+
+This is a (non-exhaustive) list of annotations that are known to be in active
+use.
+
+### backstage.io/managed-by-location
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    backstage.io/managed-by-location: github:http://github.com/spotify/backstage/catalog-info.yaml
+```
+
+The value of this annotation is a so called location reference string, that
+points to the source from which the entity was originally fetched. This
+annotation is added automatically by the catalog as it fetches the data from a
+registered location, and is not meant to normally be written by humans. The
+annotation may point to any type of generic location that the catalog supports,
+so it cannot be relied on to always be specifically of type `github`, nor that
+it even represents a single file. Note also that a single location can be the
+source of many entities, so it represents a many-to-one relationship.
+
+The format of the value is `<type>:<target>`. Note that the target may also
+contain colons, so it is not advisable to naively split the value on `:` and
+expecting a two-item array out of it. The format of the target part is
+type-dependent and could conceivably even be an empty string, but the separator
+colon is always present.
+
+### backstage.io/techdocs-ref
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    backstage.io/techdocs-ref: github:https://github.com/spotify/backstage.git
+```
+
+The value of this annotation is a location reference string (see above). If this
+annotation is specified, it is expected to point to a repository that the
+TechDocs system can read and generate docs from.
+
+### backstage.io/jenkins-github-folder
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    backstage.io/jenkins-github-folder: folder-name/job-name
+```
+
+The value of this annotation is the path to a job on Jenkins, that builds this
+entity.
+
+Specifying this annotation may enable Jenkins related features in Backstage for
+that entity.
+
+### github.com/project-slug
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    github.com/project-slug: spotify/backstage
+```
+
+The value of this annotation is the so-called slug that identifies a project on
+[GitHub](https://github.com) that is related to this entity. It is on the format
+`<organization>/<project>`, and is the same as can be seen in the URL location
+bar of the browser when viewing that project.
+
+Specifying this annotation will enable GitHub related features in Backstage for
+that entity.
+
+### sentry.io/project-slug
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    sentry.io/project-slug: pump-station
+```
+
+The value of this annotation is the so-called slug (or alternatively, the ID) of
+a [Sentry](https://sentry.io) project within your organization. The organization
+slug is currently not configurable on a per-entity basis, but is assumed to be
+the same for all entities in the catalog.
+
+Specifying this annotation may enable Sentry related features in Backstage for
+that entity.
+
+### rollbar.com/project-slug
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    rollbar.com/project-slug: spotify/pump-station
+```
+
+The value of this annotation is the so-called slug (or alternatively, the ID) of
+a [Rollbar](https://rollbar.com) project within your organization. The value can
+be the format of `[organization]/[project-slug]` or just `[project-slug]`. When
+the organization slug is omitted the `app-config.yaml` will be used as a
+fallback (`rollbar.organization` followed by `organization.name`).
+
+Specifying this annotation may enable Rollbar related features in Backstage for
+that entity.
+
+## Deprecated Annotations
+
+The following annotations are deprecated, and only listed here to aid in
+migrating away from them.
+
+### backstage.io/github-actions-id
+
+This annotation was used for a while to enable the GitHub Actions feature. This
+is now instead using the [github.com/project-slug](#github-com-project-slug)
+annotation, with the same value format.
+
+## Links
+
+- [Descriptor Format: annotations](descriptor-format.md#annotations-optional)
@@ -7,18 +7,18 @@ Publishers are responsible for pushing and storing the templated skeleton after
 the values have been templated by the `Templater`. See
 [Create your own templater](./create-your-own-templater.md) for more info.

-They receive a directory or location where the templater has sucessfully run
-and is now ready to store somewhere. They also are given some other options
-which are sent from the frontend, such as the `storePath` which is a string of
-where the frontend thinks we should save this templated folder.
+They receive a directory or location where the templater has sucessfully run and
+is now ready to store somewhere. They also are given some other options which
+are sent from the frontend, such as the `storePath` which is a string of where
+the frontend thinks we should save this templated folder.

 Currently we provide the following `publishers`:

 - `github`

 This publisher is passed through to the `createRouter` function of the
-`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is supported,
-but PR's are always welcome.
+`@spotify/plugin-scaffolder-backend`. Currently, only one publisher is
+supported, but PR's are always welcome.

 An full example backend can be found
 [here](https://github.com/spotify/backstage/blob/d91c10f654475a60829fa33a5c81018e517a319a/packages/backend/src/plugins/scaffolder.ts),
@@ -1,10 +1,11 @@
 ---
 id: software-templates-index
-title: Software Templates
+title: Backstage Software Templates
+sidebar_label: Overview
 ---

 The Software Templates part of Backstage is a tool that can help you create
-Components inside Backstage. By default, it  has the ability to load skeletons of
+Components inside Backstage. By default, it has the ability to load skeletons of
 code, template in some variables, and then publish the template to some location
 like GitHub.

@@ -30,9 +30,9 @@ the documentation template.
 Create an entity from the documentation template and you will get the needed
 setup for free.

-!!! warning Currently the Backstage Software Templates are limited to create repositories
-inside GitHub organizations. You also need to generate an personal access token
-and use as an environment variable. Read more about this
+!!! warning Currently the Backstage Software Templates are limited to create
+repositories inside GitHub organizations. You also need to generate an personal
+access token and use as an environment variable. Read more about this
 [here](../software-templates/installation.md#runtime-dependencies).

 ### Manually add documentation setup to already existing repository
@@ -10,21 +10,20 @@ title: Other
 Run the following commands if you have Docker environment

 ```bash
+$ yarn install
 $ yarn docker-build
-$ docker run --rm -it -p 80:80 spotify/backstage
+$ docker run --rm -it -p 7000:7000 -e NODE_ENV=development example-backend:latest
 ```

 Then open http://localhost/ on your browser.

 ### Running with `docker-compose`

-Run the following commands if you have docker and docker-compose for a full
-example, with the example backend also deployed.
+There is also a `docker-compose.yaml` that you can use to replace the previous
+`docker run` command:

 ```bash
-$ yarn docker-build:all
+$ yarn install
+$ yarn docker-build
 $ docker-compose up
 ```
-
-Then open http://localhost:3000 on your browser to see the example app with an
-example backend.
@@ -65,6 +65,7 @@ yarn storybook # Start local storybook, useful for working on components in @bac
 yarn workspace @backstage/plugin-welcome start # Serve welcome plugin only, also supports --check

 yarn tsc # Run typecheck, use --watch for watch mode
+yarn tsc:full # Run full type checking, for example without skipLibCheck, use in CI

 yarn build # Build published versions of packages, depends on tsc

@@ -4,7 +4,8 @@ title: Running Backstage Locally
 ---

 First make sure you are using NodeJS with an Active LTS Release, currently v12.
-This is made easy with a version manager such as nvm which allows for version switching.
+This is made easy with a version manager such as nvm which allows for version
+switching.

 ```bash
 # Checking your version
@@ -171,21 +171,19 @@ The frontend container can be built with a provided command.
 ```bash
 yarn install
 yarn tsc
-yarn build
-yarn run docker-build
+yarn run docker-build:app
 ```

 Running this will simply generate a Docker container containing the contents of
-the UIs `dist` directory. The resulting container will be about 50MB in size.
+the UIs `dist` directory.

-The backend container can be built by running the following command in the
-`packages/backend` directory.
+The backend container can be built by running the following command:

 ```bash
-yarn run build-image
+yarn run docker-build
 ```

-This will create a ~500MB container called `example-backend`.
+This will create a container called `example-backend`.

 The lighthouse-audit-service container is already publicly available in Docker
 Hub and can be downloaded and ran with