First stab at doc hierarchy

Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>

.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.

docs/drafts/derive-serviceaccount.md → docs/howto/derive-service-account.md

@@ -1,6 +1,6 @@
 # Derive minimal ServiceAccount required for ClusterExtension Installation and Management
 
-OLM v1 does not have permission to install extensions on a cluster by default. In order to install a [supported bundle](../refs/supported-extensions.md), 
+OLM v1 does not have permission to install extensions on a cluster by default. In order to install a [supported bundle](../project/supported-extensions.md), 
 OLM must be provided a ServiceAccount configured with the appropriate permissions. For more information, see the [provided ServiceAccount](./provided-serviceaccount.md) documentation.
 
 This document serves as a guide for how to derive the RBAC necessary to install a bundle.
@@ -12,6 +12,7 @@ This bundle image contains all the manifests that make up the extension (e.g. `C
 as well as a [`ClusterServiceVersion`](https://olm.operatorframework.io/docs/concepts/crds/clusterserviceversion/) (CSV) that describes the extension and its service account's permission requirements.
 
 The service account must have permissions to:
+
  - create and manage the extension's `CustomResourceDefinition`s
  - create and manage the resources packaged in the bundle
  - grant the extension controller's service account the permissions it requires for its operation

docs/tasks/upgrade/how-to-channel-based-upgrades.md → docs/howto/how-to-channel-based-upgrades.md

@@ -1,4 +1,4 @@
-## How-to: Channel-Based Automatic Upgrades
+# Channel-Based Automatic Upgrades
 
 A "channel" is a package author defined stream of updates for an extension. A set of channels can be set in the Catalog source to restrict automatic updates to the set of versions defined in those channels.
 

docs/tasks/upgrade/how-to-pin-version.md → docs/howto/how-to-pin-version.md

@@ -1,4 +1,4 @@
-## How-to: Version Pin and Disable Automatic Updates
+# Pin Version and Disable Automatic Updates
 
 To disable automatic updates, and pin the version of an extension, set `version` in the Catalog source to a specific version (e.g. 1.2.3).
 
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md)
+For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)

docs/tasks/upgrade/how-to-version-range-upgrades.md → docs/howto/how-to-version-range-upgrades.md

@@ -1,4 +1,4 @@
-## How-to: Version Range Automatic Updates
+# Version Range Automatic Updates
 
 Set the version for the desired package in the Catalog source to a comparison string, like  `">=3.0, <3.6"`, to restrict the automatic updates to the version range. Any new version of the extension released in the catalog within this range will be automatically applied.
 
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version-rages](../../refs/version-ranges.md)
+For more information on SemVer version ranges see [version-rages](../concepts/version-ranges.md)

docs/tasks/upgrade/how-to-z-stream-upgrades.md → docs/howto/how-to-z-stream-upgrades.md

@@ -1,4 +1,4 @@
-## How-to: Z-Stream Automatic Updates
+# Z-Stream Automatic Updates
 
 To restrict automatic updates to only z-stream patches and avoid breaking changes, use the `"~"` version range operator when setting the version for the desired package in Catalog source.
 
@@ -21,4 +21,4 @@ spec:
       name: argocd-installer
 ```
 
-For more information on SemVer version ranges see [version ranges](../../refs/version-ranges.md)
+For more information on SemVer version ranges see [version ranges](../concepts/version-ranges.md)