Order branches and commits where loaded, remove marshal overrides

Author: deepsm007

OC_ADM_RELEASE_COMMAND.md

@@ -0,0 +1,246 @@
+# Full `oc adm release new` Command Structure
+
+Based on the code in `pkg/steps/release/create_release.go`, here's how the complete `oc adm release new` command is constructed.
+
+## Command Builder Function
+
+The command is built by `buildOcAdmReleaseNewCommand()` at **line 314-335** in `pkg/steps/release/create_release.go`.
+
+## Base Command Structure
+
+```bash
+oc adm release new \
+  --max-per-registry=32 \
+  -n <namespace> \
+  --from-image-stream <streamName> \
+  --to-image-base <cvo> \
+  --to-image <destination> \
+  --name <version>
+```
+
+## Parameter Sources
+
+### 1. `--max-per-registry=32`
+- **Fixed value**: Always `32`
+- **Location**: Line 316
+
+### 2. `-n <namespace>`
+- **Source**: `s.jobSpec.Namespace()` (the CI job namespace)
+- **Example**: `ci-op-abc123` or `ci-op-xyz789`
+- **Location**: Line 317
+
+### 3. `--from-image-stream <streamName>`
+- **Source**: `api.ReleaseStreamFor(s.name)` (line 145)
+- **Logic**: 
+  - If `s.name == "latest"` → `"stable"`
+  - Otherwise → `"stable-{s.name}"` (e.g., `"stable-initial"`, `"stable-4.21-quay"`)
+- **Location**: Line 318
+- **Example values**:
+  - For release name `"latest"`: `stable`
+  - For release name `"initial"`: `stable-initial`
+  - For release name `"4.21-quay"`: `stable-4.21-quay`
+
+### 4. `--to-image-base <cvo>`
+- **Source**: Cluster Version Operator pull spec resolved from the ImageStream
+- **Resolution**: `util.ResolvePullSpec(stable, "cluster-version-operator", true)` (line 152)
+- **Example**: `registry.build02.ci.openshift.org/ci-op-abc/stable:cluster-version-operator`
+- **Location**: Line 319
+
+### 5. `--to-image <destination>`
+- **Source**: `fmt.Sprintf("%s:%s", releaseImageStreamRepo, s.name)` (line 171)
+- **Format**: `<releaseImageStreamRepo>:<releaseName>`
+- **Example**: `registry.build02.ci.openshift.org/ci-op-abc/release:latest`
+- **Location**: Line 320
+
+### 6. `--name <version>`
+- **Source**: Generated version string (line 169)
+- **Format**: `{prefix}-{timestamp}-test-{namespace}-{releaseName}`
+- **Prefix logic**:
+  - Default: `"0.0.1-0"`
+  - If ImageStream has `ReleaseConfigAnnotation`: Uses resolved config name
+- **Timestamp**: `time.Now().UTC().Truncate(time.Second).Format("2006-01-02-150405")`
+- **Example**: `0.0.1-0-2024-01-15-143022-ci-op-abc-latest`
+- **Location**: Line 321
+
+## Conditional Flags
+
+### `--keep-manifest-list` (for OpenShift 4.11+)
+- **Condition**: `hasMinimumVersion(config, 4, 11)` returns true
+- **Logic**: Parses `config.Name` as `major.minor` (e.g., "4.21" → major=4, minor=21)
+- **Added if**: `major > 4 || (major == 4 && minor >= 11)`
+- **Location**: Lines 331-333
+
+### `--reference-mode=source` (for OpenShift 4.13+ with SourceTagReferencePolicy)
+- **Condition**: 
+  - `config.ReferencePolicy != nil`
+  - `hasMinimumVersion(config, 4, 13)` returns true
+  - `*config.ReferencePolicy == imagev1.SourceTagReferencePolicy`
+- **Location**: Lines 324-327
+
+## Complete Example Commands
+
+### Example 1: OpenShift 4.21 (latest release, with keep-manifest-list)
+
+```bash
+oc adm release new \
+  --max-per-registry=32 \
+  -n ci-op-abc123 \
+  --from-image-stream stable \
+  --to-image-base registry.build02.ci.openshift.org/ci-op-abc123/stable:cluster-version-operator \
+  --to-image registry.build02.ci.openshift.org/ci-op-abc123/release:latest \
+  --name 0.0.1-0-2024-01-15-143022-ci-op-abc123-latest \
+  --keep-manifest-list
+```
+
+### Example 2: OpenShift 4.21-quay (custom release name)
+
+```bash
+oc adm release new \
+  --max-per-registry=32 \
+  -n ci-op-abc123 \
+  --from-image-stream stable-4.21-quay \
+  --to-image-base registry.build02.ci.openshift.org/ci-op-abc123/stable-4.21-quay:cluster-version-operator \
+  --to-image registry.build02.ci.openshift.org/ci-op-abc123/release:4.21-quay \
+  --name 0.0.1-0-2024-01-15-143022-ci-op-abc123-4.21-quay \
+  --keep-manifest-list
+```
+
+### Example 3: OpenShift 4.15 with SourceTagReferencePolicy
+
+```bash
+oc adm release new \
+  --max-per-registry=32 \
+  -n ci-op-abc123 \
+  --from-image-stream stable \
+  --to-image-base registry.build02.ci.openshift.org/ci-op-abc123/stable:cluster-version-operator \
+  --to-image registry.build02.ci.openshift.org/ci-op-abc123/release:latest \
+  --name 0.0.1-0-2024-01-15-143022-ci-op-abc123-latest \
+  --reference-mode=source \
+  --keep-manifest-list
+```
+
+### Example 4: OpenShift 4.10 (no keep-manifest-list)
+
+```bash
+oc adm release new \
+  --max-per-registry=32 \
+  -n ci-op-abc123 \
+  --from-image-stream stable \
+  --to-image-base registry.build02.ci.openshift.org/ci-op-abc123/stable:cluster-version-operator \
+  --to-image registry.build02.ci.openshift.org/ci-op-abc123/release:latest \
+  --name 0.0.1-0-2024-01-15-143022-ci-op-abc123-latest
+```
+
+## Command Execution Context
+
+The command is executed inside a Pod with:
+
+1. **Setup** (lines 189-199):
+   - Sets up authentication via `oc registry login`
+   - Uses Docker config from `/pull/.dockerconfigjson` if available
+
+2. **Retry Logic** (lines 201-214):
+   - Retries up to 5 times with 60-second delays
+   - Captures exit codes properly
+
+3. **Post-Execution** (lines 218-232):
+   - Extracts release payload: `oc adm release extract --from=<destination> --to=${ARTIFACT_DIR}/release-payload-<name>`
+   - Also retries up to 5 times
+
+## Code References
+
+- **Command builder**: `pkg/steps/release/create_release.go:314-335`
+- **Command execution**: `pkg/steps/release/create_release.go:188-236`
+- **Stream name resolution**: `pkg/api/graph.go:312-318`
+- **Version detection**: `pkg/steps/release/create_release.go:301-312`
+- **Test examples**: `pkg/steps/release/create_release_test.go:13-103`
+
+## How to Reference a Specific ImageStream (e.g., `app.ci/4.21-quay`)
+
+To reference a specific ImageStream in a different namespace (like `app.ci/4.21-quay` instead of `ocp/4.21`), you need to use the **`integration`** release type instead of `candidate`.
+
+### YAML Configuration
+
+Change your release configuration from:
+
+```yaml
+releases:
+  latest:
+    candidate:
+      product: ocp
+      stream: ci
+      version: "4.21"
+```
+
+To:
+
+```yaml
+releases:
+  latest:
+    integration:
+      namespace: app.ci
+      name: 4.21-quay
+```
+
+Or if you want to keep both:
+
+```yaml
+releases:
+  latest:
+    candidate:
+      product: ocp
+      stream: ci
+      version: "4.21"
+  4.21-quay:
+    integration:
+      namespace: app.ci
+      name: 4.21-quay
+```
+
+### How It Works
+
+1. **Snapshot Step** (`pkg/steps/release/snapshot.go:52-124`):
+   - Reads the source ImageStream from `app.ci/4.21-quay`
+   - Creates a snapshot ImageStream in the test namespace
+   - The snapshot name is `ReleaseStreamFor(releaseName)`:
+     - If release name is `"latest"` → snapshot is `stable`
+     - If release name is `"4.21-quay"` → snapshot is `stable-4.21-quay`
+
+2. **Assemble Step** (`pkg/steps/release/create_release.go:145`):
+   - Uses `ReleaseStreamFor(s.name)` to find the snapshot ImageStream in the test namespace
+   - This becomes the `--from-image-stream` parameter in the `oc adm release new` command
+
+### Complete Example
+
+For a release named `4.21-quay` referencing `app.ci/4.21-quay`:
+
+**YAML:**
+```yaml
+releases:
+  4.21-quay:
+    integration:
+      namespace: app.ci
+      name: 4.21-quay
+```
+
+**Resulting Command:**
+```bash
+oc adm release new \
+  --max-per-registry=32 \
+  -n ci-op-abc123 \
+  --from-image-stream stable-4.21-quay \
+  --to-image-base registry.build02.ci.openshift.org/ci-op-abc123/stable-4.21-quay:cluster-version-operator \
+  --to-image registry.build02.ci.openshift.org/ci-op-abc123/release:4.21-quay \
+  --name 0.0.1-0-2024-01-15-143022-ci-op-abc123-4.21-quay \
+  --keep-manifest-list
+```
+
+**Key Points:**
+- The `integration.namespace` and `integration.name` specify the **source** ImageStream (`app.ci/4.21-quay`)
+- The release name in the `releases` map determines the **snapshot** ImageStream name in the test namespace
+- The snapshot ImageStream name follows the pattern: `stable-{releaseName}` (or just `stable` if release name is `latest`)
+- Code references:
+  - Integration handling: `pkg/defaults/defaults.go:223-233`
+  - Snapshot creation: `pkg/steps/release/snapshot.go:56-124`
+  - Integration type definition: `pkg/api/types.go:331-342`
+