docs: adds clarification to imageset reference and examples

docs/design/workflows.md

@@ -13,7 +13,10 @@ Design: oc-mirror Workflows Overview
 
 ### Heads-Only
 
-The heads-only workflow is the default for both catalog and platform content types. This workflow, when initially publishing an imageset, will only mirror the channel heads for each content type. On the subsequent runs, the latest versions will be mirrored.
+The heads-only workflow is the default for both catalog and platform content types. 
+This workflow, when initially publishing an imageset, will only mirror the channel heads for each content type. 
+On the subsequent runs, the latest differential versions will be mirrored. 
+In other words, the `minVersion` is stored and managed in the metadata, and later versions are mirrored in an additive way.
 
 Heads-only is the default workflow and is controlled by the `full` key, which is set to false by default.
 

docs/examples/imageset-config-catalog-full.yaml

@@ -0,0 +1,8 @@
+# This config demonstrates how to mirror a full catalog
+---
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+mirror:
+  operators:
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
+      full: true

docs/examples/imageset-config-catalog-headsonly.yaml

@@ -1,6 +1,9 @@
 # This config uses the headsOnly feature which will mirror the 
 # latest version of each channel within each package contained 
-# within a specified operator catalog
+# within a specified operator catalog.
+
+# IMPORTANT: This is only true if metadata for this catalog in unestablished.
+# Minimum bundle versions are managed in the metadata and the latest differential bundles will be included additively.
 ---
 apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration

docs/examples/imageset-config-filter-catalog.yaml

@@ -1,33 +1,78 @@
 # This config demonstrates how to mirror a single operator. 
 
-# By specifying a minVersion, that version and every version to the
-# specified channel's latest (HEAD) version will be mirrored. 
-
 # If a package is specified with no minVersion/maxVersion or channel, each channel's latest
 # version in the specified package will be mirrored.
 
-# If the package is specified with a minVersion and maxVersion, all bundles within that range
-# will be mirrored.
-# WARNING: Any specified channel information will override this setting. Setting versions by
-# package or channel are mutually exclusive.
+# IMPORTANT: This is only true if metadata for this package in unestablished.
+# Minimum bundle versions are managed in the metadata and the latest differential bundles will be included additively.
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+mirror:
+  operators:
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
+      packages:
+        - name: elasticsearch-operator
 ---
+# If a package is specified with a channel with no minVersion/maxVersion, only the channel's latest
+# version will be mirrored.
+
+# IMPORTANT: This is only true if metadata for this package in unestablished.
+# Minimum bundle versions are managed in the metadata and the latest differential bundles will be included additively.
 apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration
 mirror:
   operators:
     - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
       packages:
         - name: elasticsearch-operator
-          minVersion: '5.3.2-20'
+          channels:
+            - name: 'stable-v0'
 ---
+# If a package is specified with no minVersion/maxVersion or channel and full is set to true,
+# all versions in each channel will be mirrored.
 apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration
 mirror:
   operators:
     - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
+      full: true
       packages:
         - name: elasticsearch-operator
 ---
+# If a package is specified with a channel with no minVersion/maxVersion and full is set to true,
+# all version in that channel will be mirrored.
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+mirror:
+  operators:
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
+      full: true
+      packages:
+        - name: elasticsearch-operator
+          channels:
+            - name: 'stable-v0'
+---
+#minVersion and maxVersion can be set that the channel level OR the package level. If set at the package level, all channels
+# containing that version range with be included in the catalog.
+
+# WARNING: Any specified channel information will override this setting. Setting versions by
+# package or channel are mutually exclusive.
+
+
+# By specifying a minVersion, that version and every version to the
+# specified channel's latest (HEAD) version will be mirrored.
+apiVersion: mirror.openshift.io/v1alpha2
+kind: ImageSetConfiguration
+mirror:
+  operators:
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10
+      packages:
+        - name: elasticsearch-operator
+          minVersion: '5.3.2-20'
+---
+# If the package is specified with a minVersion and maxVersion, all bundles within that range
+# will be mirrored.
+
 apiVersion: mirror.openshift.io/v1alpha2
 kind: ImageSetConfiguration
 mirror:

docs/imageset-config-ref.yaml

@@ -9,19 +9,25 @@ mirror:
     architectures:
       - "s390x" # Architectures to mirror for the collection of release versions (defaults to amd64)
     channels:
-      - name: stable-4.9 # References latest stable release
+      - name: stable-4.9 # References the latest stable release
       - name: stable-4.7 # Annotation references min and max version. 
         minVersion: '4.6.13'
         maxVersion: '4.7.18'
-    graph: true # Include Cincinnati upgrade graph image in imageset
+    graph: true # Include Cincinnati upgrade graph image in imageset (defaults to false)
   operators:
-    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.8 # References entire catalog
-      full: true # full can be set to pull a full catalog and must be set to filter packages
+    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.12 # References entire catalog
+      full: false # full set to false pull the latest version for all package channels with no versions set (default to false)
       packages:
+        - name: elasticsearch-operator
+          channels:
+            - name: 'stable-v0' # Mirrors a single channel
         - name: rhacs-operator
-          minVersion: '3.67.0'
+          minVersion: '3.67.0' # Mirrors all version from the minimum version to the latest in the package
+        - name: mtc-operator
           channels:
-            - name: 'latest'
+            - name: release-1.7  # Mirrors all versions in a single channel from the min version to the max version.
+              minVersion: '1.7.0'
+              maxVersion: '1.7.5'
   additionalImages: # List of additional images to be included in imageset
     - name: registry.redhat.io/ubi8/ubi:latest
   blockedImages: # Image to block by name or regular expression