From 39bbb5279e46025ab76bbc08248677144bd429f1 Mon Sep 17 00:00:00 2001 From: Eric Peterson Date: Tue, 5 Mar 2024 16:25:42 +0100 Subject: [PATCH] Propose two new annotations to help quantify scaffolder ROI Signed-off-by: Eric Peterson --- .../software-catalog/descriptor-format.md | 11 +++++++++++ .../well-known-annotations.md | 19 +++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index b2089eccaa..c7f2998e79 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/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/hours-saved: '4' spec: owner: backstage/techdocs-core type: service @@ -736,6 +738,15 @@ 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/hours-saved]` [optional] + +The approximate number of hours (as a YAML string) representing the amount of +time saved when someone uses this template. + +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 diff --git a/docs/features/software-catalog/well-known-annotations.md b/docs/features/software-catalog/well-known-annotations.md index 70f5ff5e14..974fa80993 100644 --- a/docs/features/software-catalog/well-known-annotations.md +++ b/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