First stab at doc hierarchy

Signed-off-by: Per Goncalves da Silva <[email protected]>

.github/workflows/release.yaml

@@ -54,7 +54,7 @@ jobs:
         fi
 
     - name: Generate the operator-controller release manifests
-      if: ${{ startsWith(github.ref, 'refs/tags/v') }}
+      if: ${{ startsWith(github.ref, 'concepts/tags/v') }}
       run: |
         echo VERSION="${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
         make quickstart

README.md

@@ -16,11 +16,11 @@ OLM v1 consists of two different components:
 * operator-controller (this repository)
 * [catalogd](https://github.com/operator-framework/catalogd)
 
-For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/general/olmv1_design_decisions.md).
+For a more complete overview of OLM v1 and how it differs from OLM v0, see our [overview](docs/project/olmv1_design_decisions.md).
 
 ## Getting Started
 
-To get started with OLM v1, please see our [Getting Started](docs/general/olmv1_getting_started.md) documentation.
+To get started with OLM v1, please see our [Getting Started](docs/getting-started/olmv1_getting_started.md) documentation.
 
 ## License
 

api/v1alpha1/clusterextension_types.go

@@ -49,13 +49,13 @@ type ClusterExtensionSpec struct {
 	// for this ClusterExtension. Selection is performed by setting the sourceType.
 	//
 	// Catalog is currently the only implemented sourceType, and setting the
-	// sourcetype to "Catalog" requires the catalog field to also be defined.
+	// sourcetype to "Catalog" requires the content-management field to also be defined.
 	//
 	// Below is a minimal example of a source definition (in yaml):
 	//
 	// source:
 	//   sourceType: Catalog
-	//   catalog:
+	//   content-management:
 	//     packageName: example-package
 	//
 	Source SourceConfig `json:"source"`
@@ -76,25 +76,25 @@ const SourceTypeCatalog = "Catalog"
 
 // SourceConfig is a discriminated union which selects the installation source.
 // +union
-// +kubebuilder:validation:XValidation:rule="self.sourceType == 'Catalog' && has(self.catalog)",message="sourceType Catalog requires catalog field"
+// +kubebuilder:validation:XValidation:rule="self.sourceType == 'Catalog' && has(self.content-management)",message="sourceType Catalog requires content-management field"
 type SourceConfig struct {
 	// sourceType is a required reference to the type of install source.
 	//
 	// Allowed values are ["Catalog"]
 	//
 	// When this field is set to "Catalog", information for determining the appropriate
 	// bundle of content to install will be fetched from ClusterCatalog resources existing
-	// on the cluster. When using the Catalog sourceType, the catalog field must also be set.
+	// on the cluster. When using the Catalog sourceType, the content-management field must also be set.
 	//
 	// +unionDiscriminator
 	// +kubebuilder:validation:Enum:="Catalog"
 	SourceType string `json:"sourceType"`
 
-	// catalog is used to configure how information is sourced from a catalog. This field must be defined when sourceType is set to "Catalog",
+	// content-management is used to configure how information is sourced from a content-management. This field must be defined when sourceType is set to "Catalog",
 	// and must be the only field defined for this sourceType.
 	//
 	// +optional.
-	Catalog *CatalogSource `json:"catalog,omitempty"`
+	Catalog *CatalogSource `json:"content-management,omitempty"`
 }
 
 // ClusterExtensionInstallConfig is a union which selects the clusterExtension installation config.
@@ -152,7 +152,7 @@ type ClusterExtensionInstallConfig struct {
 	Preflight *PreflightConfig `json:"preflight,omitempty"`
 }
 
-// CatalogSource defines the required fields for catalog source.
+// CatalogSource defines the required fields for content-management source.
 type CatalogSource struct {
 	// packageName is a reference to the name of the package to be installed
 	// and is used to filter the content from catalogs.
@@ -319,7 +319,7 @@ type CatalogSource struct {
 	Selector metav1.LabelSelector `json:"selector,omitempty"`
 
 	// upgradeConstraintPolicy is an optional field that controls whether
-	// the upgrade path(s) defined in the catalog are enforced for the package
+	// the upgrade path(s) defined in the content-management are enforced for the package
 	// referenced in the packageName field.
 	//
 	// Allowed values are: ["CatalogProvided", "SelfCertified"].
@@ -484,10 +484,10 @@ type ClusterExtensionStatus struct {
 	//   - "Resolved", represents whether or not a bundle was found that satisfies the selection criteria outlined in the spec
 	//   - "Unpacked", represents whether or not the bundle contents have been successfully unpacked
 	//
-	// When the ClusterExtension is sourced from a catalog, the following conditions are also possible:
+	// When the ClusterExtension is sourced from a content-management, the following conditions are also possible:
 	//   - "Deprecated", represents an aggregation of the PackageDeprecated, ChannelDeprecated, and BundleDeprecated condition types
-	//   - "PackageDeprecated", represents whether or not the package specified in the spec.source.catalog.packageName field has been deprecated
-	//   - "ChannelDeprecated", represents whether or not any channel specified in spec.source.catalog.channels has been deprecated
+	//   - "PackageDeprecated", represents whether or not the package specified in the spec.source.content-management.packageName field has been deprecated
+	//   - "ChannelDeprecated", represents whether or not any channel specified in spec.source.content-management.channels has been deprecated
 	//   - "BundleDeprecated", represents whether or not the installed bundle is deprecated
 	//
 	// The current set of reasons are:

config/base/crd/bases/olm.operatorframework.io_clusterextensions.yaml

@@ -454,8 +454,8 @@ spec:
                 - sourceType
                 type: object
                 x-kubernetes-validations:
-                - message: sourceType Catalog requires catalog field
-                  rule: self.sourceType == 'Catalog' && has(self.catalog)
+                - message: sourceType Catalog requires content-management field
+                  rule: self.sourceType == 'Catalog' && has(self.content-management)
             required:
             - install
             - source

config/samples/catalogd_operatorcatalog.yaml

@@ -6,5 +6,5 @@ spec:
   source:
     type: image
     image:
-      ref: quay.io/operatorhubio/catalog:latest
+      ref: quay.io/operatorhubio/content-management:latest
       pollInterval: 10m

docs/refs/controlling-catalog-selection.md → docs/concepts/controlling-catalog-selection.md

@@ -27,7 +27,7 @@ spec:
   catalog:
     selector:
       matchLabels:
-        olm.operatorframework.io/metadata.name: my-catalog
+        olm.operatorframework.io/metadata.name: my-content-management
 ```
 
 In this example, only the catalog named `my-catalog` will be considered when resolving `my-package`.
@@ -93,7 +93,7 @@ spec:
         - key: olm.operatorframework.io/metadata.name
           operator: NotIn
           values:
-            - unwanted-catalog
+            - unwanted-content-management
 ```
 
 This excludes the catalog named `unwanted-catalog` from consideration.
@@ -134,7 +134,7 @@ spec:
   source:
     type: image
     image:
-      ref: quay.io/example/high-priority-catalog:latest
+      ref: quay.io/example/high-priority-content-management:latest
 ```
 
 Catalogs have a default priority of `0`. The priority can be any 32-bit integer. Catalogs with higher priority values are preferred during bundle resolution.
@@ -171,7 +171,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
      source:
        type: image
        image:
-         ref: quay.io/example/catalog-a:latest
+         ref: quay.io/example/content-management-a:latest
    ```
 
    ```yaml
@@ -186,7 +186,7 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
      source:
        type: image
        image:
-         ref: quay.io/example/catalog-b:latest
+         ref: quay.io/example/content-management-b:latest
    ```
    NB: an `olm.operatorframework.io/metadata.name` label will be added automatically to ClusterCatalogs when applied
 
@@ -209,8 +209,8 @@ If the system cannot resolve to a single bundle due to ambiguity, it will genera
 3. **Apply the Resources**
 
    ```shell
-   kubectl apply -f catalog-a.yaml
-   kubectl apply -f catalog-b.yaml
+   kubectl apply -f content-management-a.yaml
+   kubectl apply -f content-management-b.yaml
    kubectl apply -f install-my-operator.yaml
    ```
 

docs/refs/single-owner-objects.md → docs/concepts/single-owner-objects.md

@@ -1,4 +1,3 @@
-
 # OLM Ownership Enforcement for `ClusterExtensions`
 
 In OLM, **a Kubernetes resource can only be owned by a single `ClusterExtension` at a time**. This ensures that resources within a Kubernetes cluster are managed consistently and prevents conflicts between multiple `ClusterExtensions` attempting to control the same resource.
@@ -15,6 +14,7 @@ Operator bundles provide `CustomResourceDefinitions` (CRDs), which are part of a
 
 
 ### 2. `ClusterExtensions` Cannot Share Objects
+
 OLM's single-owner policy means that **`ClusterExtensions` cannot share ownership of any resources**. If one `ClusterExtension` manages a specific resource (e.g., a `Deployment`, `CustomResourceDefinition`, or `Service`), another `ClusterExtension` cannot claim ownership of the same resource. Any attempt to do so will be blocked by the system.
 
 ## Error Messages

docs/tasks/upgrade/upgrade-support.md → docs/concepts/upgrade-support.md

@@ -1,3 +1,8 @@
+---
+hide:
+  - toc
+---
+
 # Upgrade support
 
 This document explains how OLM v1 handles upgrades.

docs/refs/version-ranges.md → docs/concepts/version-ranges.md

@@ -4,7 +4,7 @@ This document explains how to specify a version range to install or update an ex
 
 You define a version range in a ClusterExtension's custom resource (CR) file.
 
-## Specifying a version range in the CR
+### Specifying a version range in the CR
 
 If you specify a version range in the ClusterExtension's CR, OLM 1.0 installs or updates the latest version of the extension that can be resolved within the version range.
 The resolved version is the latest version of the extension that satisfies the dependencies and constraints of the extension and the environment.

docs/contribute/contributing.md

@@ -0,0 +1 @@
+../../CONTRIBUTING.md

docs/general/olmv1_getting_started.md → docs/getting-started/olmv1_getting_started.md

@@ -1,4 +1,8 @@
-# Getting Started with OLM v1
+---
+hide:
+  - navigation
+
+---
 
 ### Installation
 
@@ -14,7 +18,7 @@ The latest version of Operator Controller can be installed with the following co
 curl -L -s https://github.com/operator-framework/operator-controller/releases/latest/download/install.sh | bash -s
 ```
 
-## Getting Started with OLM v1
+### Getting Started with OLM v1
 
 This quickstart procedure will guide you through the following processes:
 
@@ -80,7 +84,7 @@ and on the extension upgrade process [here](./docs/drafts/Tasks/upgrading-an-ext
 
 ```bash
 # Update to v0.11.0
-kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"catalog": {"version": "0.11.0"}}}}'
+kubectl patch clusterextension argocd --type='merge' -p '{"spec": {"source": {"content-management": {"version": "0.11.0"}}}}'
 
 ```
 
@@ -96,7 +100,7 @@ remove all resources created by the extension. More information on uninstalling
 kubectl delete clusterextension/argocd
 ```
 
-#### Cleanup
+### Cleanup
 
 Extension installation requires the creation of a namespace, an installer service account, and its RBAC. Once the
 extension is uninstalled, these resources can be cleaned up.