From 3b79c042698cf3dfee923cf8865c1b0629710c29 Mon Sep 17 00:00:00 2001
From: Jerop <jerop@google.com>
Date: Wed, 26 Jan 2022 13:58:38 -0500
Subject: [PATCH] TEP-0079: Tekton Catalog Support Tiers [Catalog Annotations]

In this change, we update the `tekton.dev/catalog` annotation
to use the URL of the Catalog instead of its name. This makes
it easier for users to know which Catalog the resource came
from, especially when they have other Catalogs beyond those
provided by Tekton.
---
 teps/0079-tekton-catalog-support-tiers.md | 35 ++++++++++++++++++++---
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/teps/0079-tekton-catalog-support-tiers.md b/teps/0079-tekton-catalog-support-tiers.md
index af85a523d..78d067f57 100644
--- a/teps/0079-tekton-catalog-support-tiers.md
+++ b/teps/0079-tekton-catalog-support-tiers.md
@@ -351,21 +351,48 @@ it may be difficult to identify which Tekton Catalog it came from
 because they won't have the labels added by the CLI.
 
 To make it easy for users to identify the source Catalog, we propose 
-adding a `tekton.dev/catalog` annotation to the resource yaml file, 
-as such:
+adding two annotations:
+* `tekton.dev/catalog` with the three part domain unique identifier
+* `tekton.dev/catalog-url` with the repository path of the Catalog
 
 ```yaml
 # resource from the community catalog
 annotations:
   tekton.dev/pipelines.minVersion: "0.17.0"
   tekton.dev/tags: golang-lint
-  tekton.dev/catalog: community
+  tekton.dev/catalog: dev.tekton.catalog-community
+  tekton.dev/catalog-url: https://github.com/tektoncd/catalog
 
 # resource from the official catalog
 annotations:
   tekton.dev/pipelines.minVersion: "0.30.0"
   tekton.dev/tags: golang-fuzz
-  tekton.dev/catalog: official
+  tekton.dev/catalog: dev.tekton.catalog-official
+  tekton.dev/catalog-url: https://github.com/tektoncd/catalog-official
+```
+
+A Catalog URL (repository URL) can be changed and a resource can be moved.
+As such, we cannot rely on the Catalog URL for provenance of a resource.
+The three part domain allows us to identify the provider of the resource
+and users can rely on it remaining the same.
+
+In addition, a company can provide their own Catalogs to their users which
+would have their respective company's domain, for example:
+
+```yaml
+# resource from the openshift catalog
+annotations:
+  tekton.dev/pipelines.minVersion: "0.17.0"
+  tekton.dev/tags: openshift-build
+  tekton.dev/catalog: com.redhat.openshift
+  tekton.dev/catalog-url: https://github.com/openshift/catalog
+
+# resource from the gke catalog
+annotations:
+  tekton.dev/pipelines.minVersion: "0.30.0"
+  tekton.dev/tags: gke-build
+  tekton.dev/catalog: com.google.gke
+  tekton.dev/catalog-url: https://github.com/gke/catalog
 ```
 
 #### Community and Official Catalogs in Tekton Bundles