Merge pull request #2280 from spotify/freben/wellknown

docs(catalog): document the current set of well known annotations

docs/features/software-catalog/descriptor-format.md

@@ -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

docs/features/software-catalog/well-known-annotations.md

@@ -0,0 +1,116 @@
+---
+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.
+
+## 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)

plugins/sentry-backend/src/service/sentry-api.ts

@@ -26,7 +26,7 @@ export function getRequestHeaders(token: string) {
 }
 
 export function getSentryApiForwarder(token: string, logger: Logger) {
-  return function fowardRequest(
+  return function forwardRequest(
     request: express.Request,
     response: express.Response,
   ) {