Update with feedback

Signed-off-by: Marvin Beckers <[email protected]>

Author: embik

designs/multi-cluster.md

@@ -38,7 +38,7 @@ objects. This proposal is about adding native support for multi-cluster use-case
 to controller-runtime.
 
 With this change, it will be possible to implement pluggable cluster providers
-that automatically start and stop watches (and thus, cluster-aware reconcilers) when
+that automatically start and stop sources (and thus, cluster-aware reconcilers) when
 the cluster provider adds ("engages") or removes ("disengages") a cluster.
 
 ## Motivation
@@ -58,19 +58,18 @@ This change is important because:
 
 - Provide an interface for plugging in a "cluster provider", which provides a dynamic set of clusters that should be reconciled by registered controllers.
 - Provide a way to natively write controllers that
-  1. (UNIFORM MULTI-CLUSTER CONTROLLER) operate on multiple clusters in a uniform way,
+  1. use the cluster provider Go interface that can be implemented by 3rd parties outside of controller-runtime to adapt an existing multi-cluster-compatible code-base to a concrete environment.
+  2. (UNIFORM MULTI-CLUSTER CONTROLLER) operate on multiple clusters in a uniform way,
      i.e. reconciling the same resources on multiple clusters, **optionally**
      - sourcing information from one central hub cluster
      - sourcing information cross-cluster.
 
      Example: distributed `ReplicaSet` controller, reconciling `ReplicaSets` on multiple clusters.
-  2. (AGGREGATING MULTI-CLUSTER CONTROLLER) operate on one central hub cluster aggregating information from multiple clusters.
+  3. (AGGREGATING MULTI-CLUSTER CONTROLLER) operate on one central hub cluster aggregating information from multiple clusters.
 
      Example: distributed `Deployment` controller, aggregating `ReplicaSets` across multiple clusters back into a central `Deployment` object.
 - Allow clusters to dynamically join and leave the set of clusters a controller operates on.
 - Allow logical clusters where a set of clusters is actually backed by one physical informer store.
-- Allow 3rd-parties to plug in their multi-cluster adapter (in source code) into
-  an existing multi-cluster-compatible code-base.
 - Minimize the amount of changes to make a controller-runtime controller 
   multi-cluster-compatible, in a way that 3rd-party projects have no reason to
   object these kind of changes.
@@ -231,9 +230,16 @@ if err != nil {
 client := cl.GetClient()
 ```
 
-Due to the BYO `request` type, controllers need to be built like this:
+Due to the BYO `request` type, controllers need to be built/changed like this:
 
 ```golang
+// previous
+builder.TypedControllerManagedBy[reconcile.Request](mgr).
+	Named("single-cluster-controller").
+	For(&corev1.Pod{}).
+	Complete(reconciler)
+
+// new
 builder.TypedControllerManagedBy[ClusterRequest](mgr).
 	Named("multi-cluster-controller").
 	Watches(&corev1.Pod{}, &ClusterRequestEventHandler{}).