Merge pull request #23401 from backstage/roi/scaffolder-metadata

Standard entity metadata to help measure Scaffolder ROI

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

@@ -659,6 +659,8 @@ metadata:
   name: v1beta2-demo
   title: Test Action template
   description: scaffolder v1beta2 template demo
+  annotations:
+    backstage.io/time-saved: PT4H
 spec:
   owner: backstage/techdocs-core
   type: service
@@ -736,6 +738,16 @@ A list of strings that can be associated with the template, e.g.
 This list will also be used in the frontend to display to the user so you can
 potentially search and group templates by these tags.
 
+### `metadata.annotations.[backstage.io/time-saved]` [optional]
+
+An ISO 8601 duration representing the approximate amount of time saved when
+someone uses this template (e.g. `PT8H` to mean "8 hours saved" or `PT15M` to
+mean "15 minutes saved").
+
+Can be used in combination with the `backstage.io/source-template` annotation,
+or analytics data, to calculate how much time has been saved through the use
+of the Scaffolder plugin.
+
 ### `spec.type` [required]
 
 The type of component created by the template, e.g. `website`. This is used for

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

@@ -146,6 +146,25 @@ repository itself. If the URL points to a folder, it is important that it is
 suffixed with a `'/'` in order for relative path resolution to work
 consistently.
 
+### backstage.io/source-template
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    backstage.io/source-template: template:default/create-react-app-template
+```
+
+Represents the entity ref of the Scaffolder template that was originally used
+to create the given entity. Useful to power "create something similar"
+experiences, as well as to track adherence to software standards across the
+Catalog.
+
+Note that this value is only automatically added to an entity when the
+`catalog:write` action is used to create the `catalog-info.yaml` file. It is
+otherwise the template author's responsibility to ensure that any entity
+definition included as part of the template contains this annotation.
+
 ### jenkins.io/job-full-name
 
 ```yaml

docs/plugins/analytics.md

@@ -64,7 +64,7 @@ installed, may be captured.
 | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `navigate`  | The URL of the page that was navigated to.                                                                                                                         | Fired immediately when route location changes (unless associated plugin/route data is ambiguous, in which case the event is fired after plugin/route data becomes known, immediately before the next event or document unload). The parameters of the current route will be included as attributes. |
 | `click`     | The text of the link that was clicked on.                                                                                                                          | The `to` attribute represents the URL clicked to.                                                                                                                                                                                                                                                   |
-| `create`    | The `name` of the software being created; if no `name` property is requested by the given Software Template, then the string `new {templateName}` is used instead. | The context holds an `entityRef`, set to the template's ref (e.g. `template:default/template-name`).                                                                                                                                                                                                |
+| `create`    | The `name` of the software being created; if no `name` property is requested by the given Software Template, then the string `new {templateName}` is used instead. | The context holds an `entityRef`, set to the template's ref (e.g. `template:default/template-name`). The `value` represents the number of minutes saved by running the template (based on the template's `backstage.io/time-saved` annotation, if available).                                       |
 | `search`    | The search term entered in any search bar component.                                                                                                               | The context holds `searchTypes`, representing `types` constraining the search. The `value` represents the total number of search results for the query. This may not be visible if the permission framework is being used.                                                                          |
 | `discover`  | The title of the search result that was clicked on                                                                                                                 | The `value` is the result rank. A `to` attribute is also provided.                                                                                                                                                                                                                                  |
 | `not-found` | The path of the resource that resulted in a not found page                                                                                                         | Fired by at least TechDocs.                                                                                                                                                                                                                                                                         |