Add release automation and documentation

.github/workflows/build-packages.yml

@@ -1,22 +1,47 @@
 ---
 name: Build and Test Python Packages
 
+# Reusable build/validation workflow; callable via push/PR or workflow_call.
 on:
   push:
     branches:
       - main
-    tags:
-      - 'v*'
   pull_request:
     branches:
       - main
+  workflow_call:
+    inputs:
+      python_versions:
+        description: 'JSON array of Python versions for the matrix, e.g. ["3.11","3.13"]'
+        required: false
+        type: string
+        default: '["3.11","3.13"]'
+      publish_packages:
+        description: 'Set true to build from sdist and publish to PyPI'
+        required: false
+        type: boolean
+        default: false
 
 jobs:
   build:
     runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      id-token: write  # Required when publishing via Trusted Publishing
+    # Flag release mode based on trigger inputs or tagged builds.
+    env:
+      SHOULD_PUBLISH: >-
+        ${{ (github.event_name == 'workflow_call' && inputs.publish_packages)
+            || (github.event_name != 'workflow_call'
+            && (github.ref matches '^refs/tags/v[0-9]+\\.[0-9]+\\.[0-9]+$')) }}
     strategy:
       matrix:
-        python-version: ["3.11", "3.13"]
+        python-version: >-
+          ${{ fromJson(
+            github.event_name == 'workflow_call' && inputs.python_versions != ''
+              ? inputs.python_versions
+              : '["3.11","3.13"]'
+          ) }}
 
     name: Build packages (Python ${{ matrix.python-version }})
 
@@ -31,7 +56,38 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
+      # Release-mode builders regenerate artifacts from the sdist and validate metadata.
+      - name: Install build tools for release artifacts
+        if: env.SHOULD_PUBLISH == 'true'
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build release sdist
+        if: env.SHOULD_PUBLISH == 'true'
+        run: |
+          rm -rf dist
+          python -m build --sdist --outdir dist
+
+      - name: Rebuild wheel from sdist
+        if: env.SHOULD_PUBLISH == 'true'
+        run: |
+          set -eux
+          tmp_dir="$(mktemp -d)"
+          sdist_path="$(ls dist/*.tar.gz)"
+          tar -xzf "$sdist_path" -C "$tmp_dir"
+          sdist_root="$(find "$tmp_dir" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
+          python -m build --wheel --outdir "$tmp_dir/dist" "$sdist_root"
+          cp "$tmp_dir/dist"/*.whl dist/
+
+      - name: Run Twine checks
+        if: env.SHOULD_PUBLISH == 'true'
+        run: |
+          python -m twine check dist/*
+
+      # Validation path: standard build/test workflow across matrix versions.
       - name: Build Package
+        if: env.SHOULD_PUBLISH != 'true'
         run: |
           echo "Building package (kfp-components)..."
           uv build --out-dir dist/
@@ -72,3 +128,9 @@ jobs:
           name: package-py${{ matrix.python-version }}
           path: dist/
           retention-days: 30
+
+      - name: Publish to PyPI
+        if: env.SHOULD_PUBLISH == 'true' && matrix.python-version == '3.11'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

.github/workflows/release.yml

@@ -0,0 +1,17 @@
+---
+name: Release Python Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    # Reuse build-packages.yml in publish mode for semver tags.
+    if: ${{ github.ref matches '^refs/tags/v[0-9]+\\.[0-9]+\\.[0-9]+$' }}
+    uses: ./.github/workflows/build-packages.yml
+    secrets: inherit
+    with:
+      python_versions: '["3.11"]'
+      publish_packages: true

docs/RELEASE.md

@@ -0,0 +1,78 @@
+# Release Guide
+
+This document describes how to publish the `kfp-components` package and how to react if a release needs to be withdrawn. Follow every step to keep automation, downstream consumers, and PyPI in sync.
+
+## Versioning Strategy
+
+We use [Semantic Versioning](https://semver.org/) for `kfp-components`.
+
+- **Major** (`vX.0.0`): Breaking changes or alignment with a new Kubeflow Pipelines major release. Coordinate with the Pipelines Working Group before cutting a major.
+- **Minor** (`vX.Y.0`): New components, features, or dependency bumps that stay backward compatible.
+- **Patch** (`vX.Y.Z`): Bug fixes, metadata refreshes, or documentation-only updates.
+
+All git tags **must be prefixed with `v`** (for example: `v1.11.0`). The GitHub Actions workflows ignore tags without that prefix, so `1.11.0` will not build or publish artifacts.
+
+## Pre-release Checklist
+
+1. Confirm the main branch is healthy: CI is green and `uv build` succeeds locally.
+2. Ensure all required documentation updates (including changelog entries if applicable) are committed.
+3. Make sure `pyproject.toml` already contains the release metadata you intend to publish (name, classifiers, dependencies).
+
+## Release Procedure
+
+1. **Update the version** in `pyproject.toml` under the `[project]` section.
+2. **Commit** the change with a message such as `chore: bump version to v1.11.1`.
+3. **Tag the commit** using the `v` prefix:
+
+   ```bash
+   git tag v1.11.1
+   git push origin main
+   git push origin v1.11.1
+   ```
+
+4. Wait for GitHub Actions to finish (details below). Publish release notes on GitHub after the workflow succeeds.
+
+## GitHub Actions Automation
+
+Two workflows collaborate to ship a release.
+
+### Build Validation (`.github/workflows/build-packages.yml`)
+
+- **Trigger**: pushes to `main` and pull requests targeting `main`.
+- **Behavior**:
+  - Uses a Python matrix (currently 3.11 and 3.13) to build, validate, and test the package.
+  - Uploads the artifacts for inspection. No publish occurs.
+- **What it does**:
+  - Builds wheel and source distributions with `uv build`.
+  - Validates wheel contents and metadata.
+  - Creates an isolated virtual environment and verifies that `kfp-components` installs and imports correctly.
+  - Uploads the build artifacts as workflow artifacts for traceability.
+
+### Release Pipeline (`.github/workflows/release.yml`)
+
+- **Trigger**: pushes to tags that match `vX.Y.Z` (semantic versioning with a leading `v`).
+- **How it works**:
+  - Calls the reusable `build-packages.yml` workflow with a single Python version (3.11) and `publish_packages=true`.
+  - The reusable workflow switches into “release mode,” which:
+    - Installs `build` and `twine`.
+    - Builds an sdist (`python -m build --sdist`).
+    - Unpacks the sdist into a temporary directory.
+    - Rebuilds the wheel using the unpacked sdist contents.
+    - Runs `twine check` on the sdist and wheel.
+    - Performs the same validation and import smoke tests as the main workflow.
+    - Uploads the artifacts for auditing.
+    - Publishes the release to PyPI via Trusted Publishing (GitHub Actions OIDC), so no manual credential management or `twine upload` step is required.
+
+If the workflow fails, do not push a PyPI release. Fix the failure, retag (or tag a new patch version), and rerun the pipeline.
+
+## Rollback Procedure (Yanking a Release)
+
+PyPI does **not** support deleting releases. If a published version is broken:
+
+1. Sign in to [pypi.org](https://pypi.org/) with an account that has maintainer or owner rights on `kfp-components`.
+2. Navigate to the project → **Release history**, select the release that needs to be withdrawn, and choose **Yank release**.
+3. Provide a brief explanation for the yank (PyPI will display this note to installers) and confirm.
+4. Communicate the issue in GitHub (discussion or release notes) and plan a follow-up patch release (for example `v1.11.2`) with the fix.
+5. Tag and publish the new patch release following the standard procedure.
+
+Do **not** attempt to reuse a yanked version number. Always increment the patch version for the corrective release.