Update config readme (#2065)

Also update config comments to make it clear where features are
supposed to be listed.

Signed-off-by: Todd Short <[email protected]>

Author: tmshort

config/README.md

@@ -1,77 +1,79 @@
-# OPERATOR-CONTROLLER CONFIG
+# OPERATOR-CONTROLLER CONFIGURATION
+
+The main kustomize targets are all located in the `config/overlays` directory. These are the directories that should be passed to kustomize:
+
+e.g.
+```
+kustomize build config/overlays/standard > standard.yaml
+```
+
+# Overlays
+
+All other directories are in support of of these overlays.
 
 ## config/overlays/basic-olm
 
-This includes basic support for an insecure OLMv1 deployment. This configuration uses:
-* config/base/catalogd
-* config/base/operator-controller
-* config/base/common
+This includes basic support for an insecure (non-TLS) OLMv1 deployment.
+
+## config/overlays/standard
+
+This includes support for a secure (i.e. with TLS) configuration of OLMv1. This configuration requires cert-manager.
+
+This configuration is used to generate `manifests/standard.yaml`.
 
-## config/overlays/cert-manager
+## config/overlays/standard-e2e
 
-This includes support for a secure (i.e. with TLS) configuration of OLMv1. This configuration uses:
-* config/base/catalogd
-* config/base/operator-controller
-* config/base/common
-* config/components/tls/catalogd
-* config/components/tls/operator-controller
-* config/components/tls/ca
+This provides additional configuration support for end-to-end testing, including code coverage. This configuration requires cert-manager.
 
-This configuration requires cert-manager.
+This configuration is used to generate `manifests/standard-e2e.yaml`.
 
-## config/overlays/e2e
+## config/overlays/experimental
 
-This provides additional configuration support for end-to-end testing, including code coverage. This configuration uses:
-* config/base/catalogd
-* config/base/operator-controller
-* config/base/common
-* config/components/coverage
-* config/components/tls/catalogd
-* config/components/tls/operator-controller
-* config/components/tls/ca
+This provides additional configuration used to support experimental features, including CRDs. This configuration requires cert-manager.
 
-This configuration requires cert-manager.
+This configuration is used to generate `manifests/experimental.yaml`.
 
-## Base Configuration
+## config/overlays/experimental-e2e
 
-The base configuration specifies a namespace of `olmv1-system`.
+This provides experimental configuration and support for end-to-end testing, includng code coverage. This configuration requires cert-manager.
 
-### config/base/catalogd
+This configuration is used to generate `manifests/experimental-e2e.yaml`.
 
-This provides the base configuration of catalogd.
+## config/overlays/tilt-local-dev
 
-### config/base/operator-controller
+This provides configuration for Tilt debugging support.
 
-This provides the base configuration of operator-controller.
+# Components
 
-### config/base/common
+Components are the kustomize configuration building blocks.
 
-This provides common components to both operator-controller and catalogd, i.e. namespace.
+## config/components/base
 
-## Components
+This directory provides multiple configurations for organizing the base configuration into standard and experimental configurations.
 
-Each of the `kustomization.yaml` files specify a `Component`, rather than an overlay, and thus, can be used within the overlays.
+:bangbang: *The following rules should be followed when configurating a feature:*
 
-### config/components/tls/catalogd
+* Feature components that are GA'd and should be part of the standard manifest should be listed in `config/components/base/common/kustomization.yaml`. This `commmon` kustomization file is included by *both* the **standard** and **experimental** configurations.
+* Feature components that are still experimental and should be part of the standard manifest should be listed only in `config/components/base/experimental/kustomization.yaml`.
 
-This provides a basic configuration of catalogd with TLS support.
+## config/components/features
 
-This component requires cert-manager.
+This directory contains contains configuration for features (experimental or otherwise).
 
-### config/components/tls/operator-controller
+:bangbang: *Feature configuration should be placed into a subdirectory here.*
 
-This provides a basic configuration of operator-controller with TLS support for catalogd.
+## config/components/cert-manager
 
-This component requires cert-manager.
+This directory provides configuration for using cert-manager with OLMv1.
 
-### config/components/tls/ca
+## config/components/e2e
 
-Provides a CA for operator-controller/catalogd operation.
+This directory provides configuration for end-to-end testing of OLMv1.
 
-This component _does not_ specify a namespace, and _must_ be included last.
+# Base Configuration
 
-This component requires cert-manager.
+The `config/base` directory contains the base kubebuilder-generated configuration, along with CRDs.
 
-### config/components/coverage
+# Samples
 
-Provides configuration for code coverage.
+The `config/samples` directory contains example ClusterCatalog and ClusterExtension resources.

config/components/base/common/kustomization.yaml

@@ -6,5 +6,5 @@ resources:
 - ../../../base/operator-controller
 - ../../../base/common
 # components should include any GA'd features (none as of now)
+# they should not be listed in the standard config, as they will be excluded from the experimental manifest
 components:
-

config/components/base/standard/kustomization.yaml

@@ -7,4 +7,4 @@ resources:
 # Pull in the component(s) common to standard and experimental
 components:
 - ../common
-# GA'D FEATURES ARE LISTED HERE
+# GA'D FEATURES ARE LISTED IN THE COMMON CONFIG, NOT HERE