[hack] Add create-release-tag.py script

Adds a script to create consistent annotated release tags for WMCO.
The commit SHA is resolved from the bundle image in the Red Hat Container
Catalog (preferring the org.opencontainers.image.revision label, falling
back to the short-SHA image tag), and the tag date is set to the operator
image's push_date so the timestamp reflects the actual release date.

A --commit override is available for releases not present in the catalog
(e.g. backport-only releases), and --date allows overriding the publish
date. The script prompts for confirmation before creating the tag.

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

Author: mtnbikenc

hack/create-release-tag.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+create-release-tag.py — Create an annotated release tag for WMCO.
+
+The commit SHA is resolved from the bundle image in the Red Hat Container
+Catalog, preferring the org.opencontainers.image.revision label (full SHA)
+and falling back to the short-SHA image tag.  The tag date is set to the
+operator image's push_date so the timestamp reflects the actual release date.
+
+Usage:
+    python3 hack/create-release-tag.py <version>
+    python3 hack/create-release-tag.py <version> --commit <SHA>
+    python3 hack/create-release-tag.py <version> --date YYYY-MM-DD
+    python3 hack/create-release-tag.py <version> --commit <SHA> --date YYYY-MM-DD
+
+    --commit is required when the version has no entry in the bundle catalog
+    (e.g. backport releases that were never shipped as a container image).
+"""
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+
+import requests
+
+OPERATOR_CATALOG_API = (
+    "https://catalog.redhat.com/api/containers/v1/repositories/"
+    "registry/registry.access.redhat.com/repository/"
+    "openshift4-wincw/windows-machine-config-rhel9-operator/images"
+)
+BUNDLE_CATALOG_API = (
+    "https://catalog.redhat.com/api/containers/v1/repositories/"
+    "registry/registry.access.redhat.com/repository/"
+    "openshift4-wincw/windows-machine-config-operator-bundle/images"
+)
+
+_VERSION_TAG_RE = re.compile(r"^v(\d+\.\d+\.\d+)$")
+_HEX_RE = re.compile(r"^[0-9a-f]{7,40}$")
+
+
+# ---------------------------------------------------------------------------
+# Catalog helpers (shared pattern with verify-release.py)
+# ---------------------------------------------------------------------------
+
+def _fetch_pages(api_url: str) -> list:
+    """Fetch all image records from a catalog API endpoint, handling pagination."""
+    images, page = [], 0
+    while True:
+        resp = requests.get(api_url, params={"page_size": 100, "page": page,
+                                             "sort_by": "creation_date[desc]"}, timeout=30)
+        resp.raise_for_status()
+        batch = resp.json().get("data", [])
+        if not batch:
+            break
+        images.extend(batch)
+        if len(batch) < 100:
+            break
+        page += 1
+    return images
+
+
+def _version_from_tags(repos: list) -> str:
+    """Return the x.y.z version string from a repository's tag list, or ''."""
+    for repo in repos:
+        for tag in repo.get("tags", []):
+            m = _VERSION_TAG_RE.match(tag.get("name", ""))
+            if m:
+                return m.group(1)
+    return ""
+
+
+def _labels(img: dict) -> dict:
+    return {lbl["name"]: lbl["value"]
+            for lbl in img.get("parsed_data", {}).get("labels", [])}
+
+
+def fetch_bundle_info(version: str) -> tuple[str, str]:
+    """
+    Return (commit, source_description) for the given version from the bundle catalog.
+    Prefers the org.opencontainers.image.revision label (full SHA); falls back to
+    the short hex SHA image tag.  Returns ('', '') if the version is not found.
+    """
+    for img in _fetch_pages(BUNDLE_CATALOG_API):
+        repos = img.get("repositories", [])
+        if _version_from_tags(repos) != version:
+            continue
+        all_tags = [t.get("name", "") for repo in repos for t in repo.get("tags", [])]
+        commit = _labels(img).get("org.opencontainers.image.revision", "")
+        if commit:
+            return commit, "bundle image OCI label"
+        sha_tags = [t for t in all_tags if _HEX_RE.match(t) and not _VERSION_TAG_RE.match(t)]
+        if sha_tags:
+            return sha_tags[0], "bundle image tag (short SHA)"
+        return "", ""
+    return "", ""
+
+
+def fetch_operator_push_date(version: str) -> str:
+    """
+    Return the push_date (YYYY-MM-DD) for the given version from the operator catalog,
+    or '' if not found.
+    """
+    for img in _fetch_pages(OPERATOR_CATALOG_API):
+        for repo in img.get("repositories", []):
+            for tag in repo.get("tags", []):
+                m = _VERSION_TAG_RE.match(tag.get("name", ""))
+                if m and m.group(1) == version:
+                    push_date = repo.get("push_date", "")
+                    return push_date[:10] if push_date else ""
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Git helpers
+# ---------------------------------------------------------------------------
+
+def git(*args, env=None) -> str:
+    """Run a git command and return stdout, raising on failure."""
+    result = subprocess.run(["git", *args], capture_output=True, text=True, env=env)
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip())
+    return result.stdout.strip()
+
+
+def tag_exists(tag: str) -> bool:
+    try:
+        git("rev-parse", tag)
+        return True
+    except RuntimeError:
+        return False
+
+
+def resolve_commit(ref: str) -> str:
+    """Return the full commit SHA for ref, or raise RuntimeError."""
+    try:
+        return git("rev-parse", f"{ref}^{{commit}}")
+    except RuntimeError:
+        raise RuntimeError(
+            f"Commit '{ref}' not found in this repository.\n"
+            "Ensure your local repo is up to date: git fetch origin"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Create an annotated WMCO release tag.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""\
+Examples:
+  python3 hack/create-release-tag.py 10.21.1
+  python3 hack/create-release-tag.py 10.17.2 --commit abc1234 --date 2025-06-03
+""",
+    )
+    parser.add_argument("version", metavar="X.Y.Z",
+                        help="Release version without 'v' prefix")
+    parser.add_argument("--commit", metavar="SHA",
+                        help="Override commit SHA (required if version is not in catalog)")
+    parser.add_argument("--date", metavar="YYYY-MM-DD",
+                        help="Override published date")
+    args = parser.parse_args()
+
+    # Validate inputs
+    if not re.fullmatch(r"\d+\.\d+\.\d+", args.version):
+        parser.error(f"version must be X.Y.Z, got: {args.version!r}")
+
+    if args.date and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", args.date):
+        parser.error(f"--date must be YYYY-MM-DD, got: {args.date!r}")
+
+    version = args.version
+    tag = f"v{version}"
+    message = f"Windows Machine Config Operator {tag}"
+
+    if tag_exists(tag):
+        print(f"ERROR: Tag '{tag}' already exists. Delete it first if you intend to recreate it.",
+              file=sys.stderr)
+        sys.exit(1)
+
+    # Resolve commit
+    need_catalog = not args.commit or not args.date
+    if need_catalog:
+        print(f"Fetching release details for {tag} from Red Hat Container Catalog...", flush=True)
+
+    if args.commit:
+        commit_sha = args.commit
+        commit_source = "provided manually"
+    else:
+        commit_sha, commit_source = fetch_bundle_info(version)
+        if not commit_sha:
+            print(f"\nERROR: Could not resolve commit SHA for {tag}.", file=sys.stderr)
+            print("       The bundle image for this version may not be in the catalog.", file=sys.stderr)
+            print("       Provide the commit manually: --commit <SHA>", file=sys.stderr)
+            sys.exit(1)
+
+    if args.date:
+        published_date = args.date
+        date_source = "provided manually"
+    else:
+        published_date = fetch_operator_push_date(version)
+        date_source = "operator image push date"
+        if not published_date:
+            print(f"\nERROR: Could not resolve published date for {tag}.", file=sys.stderr)
+            print("       The operator image for this version may not be in the catalog.", file=sys.stderr)
+            print("       Provide the date manually: --date YYYY-MM-DD", file=sys.stderr)
+            sys.exit(1)
+
+    # Expand to full commit SHA and verify it exists locally
+    try:
+        full_commit = resolve_commit(commit_sha)
+    except RuntimeError as exc:
+        print(f"\nERROR: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    # Use noon UTC on the published date for an unambiguous timestamp
+    tag_date = f"{published_date}T12:00:00+0000"
+
+    # Confirm with user
+    print()
+    print("Tag details:")
+    print()
+    print(f"  {'Tag:':<10} {tag}")
+    print(f"  {'Message:':<10} {message}")
+    print(f"  {'Commit:':<10} {full_commit}  ({commit_source})")
+    print(f"  {'Date:':<10} {tag_date}  ({date_source})")
+    print()
+    try:
+        answer = input("Proceed? [y/N] ")
+    except (KeyboardInterrupt, EOFError):
+        print("\nAborted.")
+        sys.exit(0)
+
+    if answer.strip().lower() != "y":
+        print("Aborted.")
+        sys.exit(0)
+
+    # Create the annotated tag with the catalog publish date
+    env = {**os.environ, "GIT_COMMITTER_DATE": tag_date}
+    try:
+        git("tag", "-a", tag, full_commit, "-m", message, env=env)
+    except RuntimeError as exc:
+        print(f"\nERROR: Failed to create tag: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print()
+    print(f"Tag '{tag}' created. To push:")
+    print(f"  git push origin {tag}")
+
+
+if __name__ == "__main__":
+    main()