[hack] Add data source and logic summary to create-release-tag.py

Documents the two catalog sources (bundle image for commit SHA, operator
image for published date), the local git operations, and the step-by-step
logic for commit resolution, tag date resolution, tag creation, and the
push instruction — matching the style used in verify-release.py.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mtnbikenc

hack/create-release-tag.py

@@ -20,6 +20,75 @@
     Pushing tags to the upstream openshift/windows-machine-config-operator
     repository requires write access granted by the repository administrators.
     Contact the WMCO team to have your GitHub account added before pushing.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+DATA SOURCES
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Red Hat Container Catalog  (catalog.redhat.com)
+    Bundle image:    openshift4-wincw/windows-machine-config-operator-bundle
+    Provides: build commit SHA.  Newer images carry the full 40-character SHA
+    in the org.opencontainers.image.revision OCI label.  Older images that
+    predate the label are handled by falling back to the short (7-character)
+    hex SHA that Konflux publishes as an image tag alongside the version tag.
+
+    Operator image:  openshift4-wincw/windows-machine-config-rhel9-operator
+    Provides: push_date — the UTC timestamp when the image was published to the
+    catalog.  This is used as the tag date so the annotated tag timestamp
+    reflects the actual release date rather than the date the tag was created.
+
+  Local git repository
+    Provides: existing tag detection (prevents accidental overwrites), full SHA
+    expansion from short SHAs via git rev-parse, commit existence verification
+    to catch catalog/repo mismatches before the tag is written, and upstream
+    remote detection for the post-creation push instruction.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+LOGIC
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. COMMIT RESOLUTION
+   Source:   Bundle image catalog
+   Data:     org.opencontainers.image.revision label (preferred) or short hex
+             image tag (fallback for images that predate the OCI label).
+   Logic:
+     • Scans the bundle catalog for the image whose tags include vX.Y.Z.
+     • Prefers the full SHA from the OCI label; falls back to the short SHA tag.
+     • Any SHA (full or short) is expanded to a full 40-character commit via
+       git rev-parse and verified to exist locally.  This catches catalog/repo
+       mismatches (e.g. if the local clone is stale) before writing anything.
+     • --commit skips the catalog lookup entirely and uses the provided value.
+       Required for backport releases that were never shipped as a container
+       image and therefore have no bundle catalog entry.
+
+2. TAG DATE RESOLUTION
+   Source:   Operator image catalog
+   Data:     push_date field from the repository entry for the matching version.
+   Logic:
+     • The push_date is the UTC timestamp when the operator image was published.
+     • Only the date portion (YYYY-MM-DD) is used; the time is fixed to noon UTC
+       (12:00:00+0000) to produce an unambiguous, timezone-neutral timestamp.
+     • The fixed noon time is set via GIT_COMMITTER_DATE when git tag is invoked,
+       so it appears as the tag's creation date in git log and GitHub.
+     • --date skips the catalog lookup and uses the provided date instead.
+
+3. TAG CREATION
+   Logic:
+     • Tag name:    vX.Y.Z
+     • Tag message: "Windows Machine Config Operator vX.Y.Z"
+     • Tag type:    annotated (git tag -a), never lightweight.
+     • The user is shown all resolved details — tag, message, full commit SHA
+       with its source, and date with its source — and must confirm before the
+       tag is written.  This surfaces any unexpected catalog values before they
+       become permanent.
+
+4. PUSH INSTRUCTION
+   Logic:
+     • After creation, scans git remote -v for a remote whose URL contains
+       "openshift/windows-machine-config-operator" and uses its configured name
+       (commonly "upstream") in the suggested push command.
+     • Falls back to the canonical SSH URL if no matching remote is found, so
+       the command is always complete and immediately usable.
 """
 
 import argparse