Merge branch 'master' into feature/aws-assume-role

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

@@ -205,7 +205,8 @@ described below.
 
 In addition to these, you may add any number of other fields directly under
 `metadata`, but be aware that general plugins and tools may not be able to
-understand their semantics.
+understand their semantics. See [Extending the model](extending-the-model.md)
+for more information.
 
 ### `name` [required]
 
@@ -214,8 +215,8 @@ entity, and for machines and other components to reference the entity (e.g. in
 URLs or from other entity specification files).
 
 Names must be unique per kind, within a given namespace (if specified), at any
-point in time. Names may be reused at a later time, after an entity is deleted
-from the registry.
+point in time. This uniqueness constraint is case insensitive. Names may be
+reused at a later time, after an entity is deleted from the registry.
 
 Names are required to follow a certain format. Entities that do not follow those
 rules will not be accepted for registration in the catalog. The ruleset is
@@ -226,19 +227,7 @@ follows.
 - Must consist of sequences of `[a-z0-9A-Z]` possibly separated by one of
   `[-_.]`
 
-Example: `visits-tracking-service`, `CircleciBuildsDump_avro_gcs`
-
-In addition to this, names are passed through a normalization function and then
-compared to the same normalized form of other entity names and made sure to not
-collide. This rule of uniqueness exists to avoid situations where e.g. both
-`my-component` and `MyComponent` are registered side by side, which leads to
-confusion and risk. The normalization function is also configurable, but the
-default behavior is as follows.
-
-- Strip out all characters outside of the set `[a-zA-Z0-9]`
-- Convert to lowercase
-
-Example: `CircleciBuildsDs_avro_gcs` -> `circlecibuildsdsavrogcs`
+Example: `visits-tracking-service`, `CircleciBuildsDumpV2_avro_gcs`
 
 ### `namespace` [optional]
 
@@ -248,7 +237,8 @@ the same format restrictions as `name` above.
 This field is optional, and currently has no special semantics apart from
 bounding the name uniqueness constraint if specified. It is reserved for future
 use and may get broader semantic implication later. For now, it is recommended
-to not specify a namespace unless you have specific need to do so.
+to not specify a namespace unless you have specific need to do so. This means
+the entity belongs to the `"default"` namespace.
 
 Namespaces may also be part of the catalog, and are `v1` / `Namespace` entities,
 i.e. not Backstage specific but the same as in Kubernetes.
@@ -278,7 +268,6 @@ most 253 characters in total. The name part must be sequences of `[a-zA-Z0-9]`
 separated by any of `[-_.]`, at most 63 characters in total.
 
 The `backstage.io/` prefix is reserved for use by Backstage core components.
-Some keys such as `system` also have predefined semantics.
 
 Values are strings that follow the same restrictions as `name` above.
 

docs/glossary.md

@@ -9,6 +9,11 @@ The Backstage Glossary lists all the terms, abbreviations, and phrases used in
 Backstage, together with their explanations. We encourage you to use the
 terminology below for clarity and consistency when discussing Backstage.
 
+### Authentication Glossary
+
+This [page](./auth/glossary.md) directs to the terms and phrases related to
+authentication and identity section of Backstage.
+
 ### Backstage User Profiles
 
 There are three main user profiles for Backstage: the integrator, the

docs/plugins/composability.md

@@ -248,7 +248,7 @@ might be linking to, allowing the app to decide the final target. If the
 declare an `ExternalRouteRef` similar to this:
 
 ```ts
-const headerLinkRouteRef = createExternalRouteRef();
+const headerLinkRouteRef = createExternalRouteRef({ id: 'header-link' });
 ```
 
 ### Binding External Routes in the App

docs/plugins/github-apps.md

@@ -27,17 +27,17 @@ to grant the app more permissions if needed.
 
 ### Using the CLI (public GitHub only)
 
-You can use the `backstage-cli` to create GitHub App' using a manifest file that
-we provide. This gives us a way to automate some of the work required to create
-a GitHub app.
+You can use the `backstage-cli` to create a GitHub App using a manifest file
+that we provide. This gives us a way to automate some of the work required to
+create a GitHub app.
 
-You can read more about the `backstage-cli create-github-app` method
-[here](../cli/commands.md#create-github-app)
+You can read more about the
+[`backstage-cli create-github-app` method](../cli/commands.md#create-github-app).
 
-Once you've gone through the CLI command, it should produce a `yaml` file in the
+Once you've gone through the CLI command, it should produce a YAML file in the
 root of the project which you can then use as an `include` in your
-`app-config.yaml`. You can go ahead and skip to
-[here](#including-in-integrations-config) if you've got to this part.
+`app-config.yaml`. You can go ahead and
+[skip ahead](#including-in-integrations-config) if you've already got an app.
 
 ### GitHub Enterprise
 
@@ -46,9 +46,9 @@ You have to create the GitHub Application manually using these
 as GitHub Enterprise does not support creation of apps from manifests.
 
 Once the application is created you have to generate a private key for the
-application it in a `yaml` file.
+application and place it in a YAML file.
 
-The yaml file must include the following information. Please note that the
+The YAML file must include the following information. Please note that the
 indentation for the `privateKey` is required.
 
 ```yaml
@@ -64,7 +64,7 @@ privateKey: |
 
 ### Including in Integrations Config
 
-Once the credentials are stored in a yaml file generated by `create-github-app`
+Once the credentials are stored in a YAML file generated by `create-github-app`,
 or manually by following the [GitHub Enterprise](#gitHub-enterprise)
 instructions, they can be included in the `app-config.yaml` under the
 `integrations` section.
@@ -77,6 +77,6 @@ method of distributing secrets.
 integrations:
   github:
     - host: github.com
-    apps:
+      apps:
         - $include: example-backstage-app-credentials.yaml
 ```