First stab at doc hierarchy

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

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/overview/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/overview/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/contribute/contributing.md

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

docs/index.md

@@ -0,0 +1,7 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+Something nice

docs/general/architecture.md → docs/overview/olmv1_architecture.md

@@ -1,5 +1,4 @@
-
-## OLM V1 Architecture
+# OLM V1 Architecture
 
 This document describes the OLM v1 architecture. OLM v1 consists of two main components:
 

docs/general/olmv1_getting_started.md → docs/overview/olmv1_getting_started.md

@@ -80,7 +80,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"}}}}'
 
 ```
 

docs/general/olmv1_overview.md → docs/overview/olmv1_overview.md

@@ -1,15 +1,13 @@
-# Overview
+# What is Operator Lifecycle Manager (OLM)?
 
-## What is Operator Lifecycle Manager (OLM)?
-
-Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the 
-lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing, 
+Operator Lifecycle Manager (OLM) is an open-source [CNCF](https://www.cncf.io/) project with the mission to manage the
+lifecycle of cluster extensions centrally and declaratively on Kubernetes clusters. Its purpose is to make installing,
 running, and updating functional extensions to the cluster easy, safe, and reproducible for cluster administrators and PaaS administrators.
 
-Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.). 
+Previously, OLM was focused on a particular type of cluster extension: [Operators](https://operatorhub.io/what-is-an-operator#:~:text=is%20an%20Operator-,What%20is%20an%20Operator%20after%20all%3F,or%20automation%20software%20like%20Ansible.).
 Operators are a method of packaging, deploying, and managing a Kubernetes application. An Operator is composed of one or more controllers paired with one or both of the following objects:
 
-* One or more API extensions 
+* One or more API extensions
 * One or more [CustomResourceDefinitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (CRDs).
 
 OLM helped define lifecycles for these extensions: from packaging and distribution to installation, configuration, upgrade, and removal.
@@ -27,7 +25,7 @@ is a popular destination for discovering Operators, and boasts over 300 packages
 ## Why are we building OLM v1?
 
 OLM v0 has been in production for over 5 years, and the community to leverage this experience and question the initial
-goals and assumptions of the project. OLM v1 is a complete redesign and rewrite of OLM taking into account this accumulated experience. 
+goals and assumptions of the project. OLM v1 is a complete redesign and rewrite of OLM taking into account this accumulated experience.
 Compared to its predecessor, amongst other things, OLM v1 aims to provide:
 
 * A simpler API surface and mental model
@@ -37,19 +35,19 @@ Compared to its predecessor, amongst other things, OLM v1 aims to provide:
 * Helm Chart support
 * GitOps support
 
-To learn more about where v1 one came from, and where it's going, please see [The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](olmv1_design_decisions.md) 
-and our feature [Roadmap](olmv1_roadmap.md).
+To learn more about where v1 one came from, and where it's going, please see [The Road to v1: Multi-Tenancy Challenges, Lessons Learned, and Design Shifts](overview/olmv1_design_decisions.md)
+and our feature [Roadmap](overview/olmv1_roadmap.md).
 
 ## The OLM community
 
-In this next iteration of OLM, the community has also taken care to make it as contributor-friendly as possible, and welcomes new contributors. 
-The project is tracked in a [GitHub project](https://github.com/orgs/operator-framework/projects/8/), 
+In this next iteration of OLM, the community has also taken care to make it as contributor-friendly as possible, and welcomes new contributors.
+The project is tracked in a [GitHub project](https://github.com/orgs/operator-framework/projects/8/),
 which provides a great entry point to quickly find something interesting to work on and contribute.
 
 You can reach out to the OLM community for feedbacks/discussions/contributions in the following channels:
 
-  * Kubernetes Slack channel: [#olm-dev](https://kubernetes.slack.com/messages/olm-dev)
-  * [Operator Framework on Google Groups](https://groups.google.com/forum/#!forum/operator-framework)
-  * Weekly in-person Working Group meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)
+* Kubernetes Slack channel: [#olm-dev](https://kubernetes.slack.com/messages/olm-dev)
+* [Operator Framework on Google Groups](https://groups.google.com/forum/#!forum/operator-framework)
+* Weekly in-person Working Group meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group)
 
-For further information on contributing, please consult the [Contribution Guide](../../CONTRIBUTING.md)
+For further information on contributing, please consult the [Contribution Guide](../CONTRIBUTING.md)

docs/refs/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/drafts/derive-serviceaccount.md → docs/refs/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](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/refs/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/refs/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](version-ranges.md)

docs/tasks/upgrade/how-to-version-range-upgrades.md → docs/refs/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](version-ranges.md)

docs/tasks/upgrade/how-to-z-stream-upgrades.md → docs/refs/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](version-ranges.md)

docs/refs/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/refs/supported-extensions.md

@@ -2,7 +2,7 @@ Currently, OLM v1 supports installing cluster extensions that meet the following
 
 * The extension must support installation via the `AllNamespaces` install mode.
 * The extension must not use webhooks.
-* The extension must not declare dependencies using the any of  following file-based catalog properties:
+* The extension must not declare dependencies using any of the following file-based catalog properties:
 
     * `olm.gvk.required`
     * `olm.package.required`

docs/tasks/catalog/adding-a-catalog.md → docs/tasks/add-a-catalog.md

@@ -1,4 +1,4 @@
-# Adding a catalog of extensions to a cluster
+# Add a Catalog of Extensions to a Cluster
 
 Extension authors can publish their products in catalogs.
 ClusterCatalogs are curated collections of Kubernetes extensions, such as Operators.

docs/tasks/downgrade/downgrading-an-extension.md → docs/tasks/downgrade-extension.md

@@ -1,4 +1,3 @@
-
 # Downgrade a ClusterExtension
 
 ## Introduction

docs/refs/exploring-available-packages.md → docs/tasks/explore-available-content.md

@@ -1,6 +1,6 @@
-# Exploring Available Packages
+# Explore Available Content
 
-After you add a catalog of extensions to your cluster, you must port forward your catalog as a service.
+After you [add a catalog of extensions](add-a-catalog.md) to your cluster, you must port forward your catalog as a service.
 Then you can query the catalog by using `curl` commands and the `jq` CLI tool to find extensions to install.
 
 ## Prerequisites
@@ -143,4 +143,4 @@ The following examples will show this default behavior, but for simplicity's sak
 
 ### Additional resources
 
-* [Catalog queries](catalog-queries.md)
+* [Catalog queries](../refs/catalog-queries.md)