Define Release Policy for ibm/python-versions-pz

[adilhusain-s]

Define Release Policy for ibm/python-versions-pz

Context

ibm/python-versions-pz is a downstream fork of actions/python-versions (managed by Microsoft).

• Upstream builds and publishes Python artifacts used by GitHub Actions
• Supported upstream architectures: amd64, arm64
• Architectures not provided upstream: ppc64le, s390x
• Attempts to engage upstream on adding these architectures did not result in support

This repository exists to:

• Build and publish Python artifacts for ppc64le and s390x
• Remain compatible with GitHub Actions workflows
• Reference upstream artifacts for amd64 and arm64

Because this repository combines native builds with upstream references, a clearly documented release policy is needed.

---

Goal

Document and align on the release policy used by this repository, including the reasoning behind it and the expected impact, before formalizing the policy in repository documentation.

---

Release Policy, Reasoning, and Impact

1. Release Mirroring Strategy

Decision

• Follow upstream release availability for supported Python versions
• Publish artifacts for all patch (micro) versions within each supported minor series

Reasoning

• Python patch releases are intended to contain incremental bug fixes and security updates rather than feature changes.
• GitHub Actions workflows may request a specific patch version rather than a moving target.
• Limiting releases to only the most recent patch can cause otherwise valid workflows to fail when an older patch is explicitly requested.

Impact

• Improves compatibility with workflows that pin specific patch versions.
• Results in a larger number of releases, which can be automated and managed predictably.

Upstream Alignment Timing

• Builds are expected to be triggered automatically after upstream releases are detected.
• Target availability is within 24–48 hours of upstream publication where practical
  (this is a best-effort goal, not a strict guarantee).

---

2. Supported Python Versions (Lifecycle-Based)

Decision

• Publish artifacts for Python versions that are currently in bugfix or security-only status,
  as defined by the Python release lifecycle, and while upstream artifacts continue to be published.

Reasoning

• Python versions progress through clearly defined lifecycle phases, including bugfix, security-only, and end-of-life.
• Using lifecycle status as the support criterion avoids embedding version numbers that can become outdated over time.
• Aligning support with upstream lifecycle and artifact availability reduces the likelihood of maintaining versions that upstream no longer publishes.

Impact

• The policy remains accurate as Python versions age or new versions are released.
• Contributors and users can rely on upstream lifecycle status as the source of truth.
• Versions that reach end-of-life naturally fall out of scope without requiring special handling.

---

3. Pre-release (Alpha / Beta) Policy

Decision

• Do not publish alpha or beta artifacts for stable minor versions.
• Publish pre-release artifacts only for the latest development minor version.

Reasoning

• Pre-release versions are published primarily for testing and early feedback and may change before a final release.
• After a minor version is released, its pre-release builds are no longer representative of the supported version.
• CPython development typically advances one future minor version at a time, making it practical to scope pre-release support accordingly.

Impact

• Reduces confusion for users consuming stable versions.
• Still allows early access for testing and contributor workflows.

---

4. Architecture Scope and Manifest Strategy

Decision

• Build and publish artifacts for:

  • ppc64le
  • s390x

• Reference upstream artifacts for:

  • amd64
  • arm64

Manifest Strategy

• The version manifest used by GitHub Actions remains compatible with upstream:

  • Upstream entries for amd64 and arm64 are preserved unchanged.
  • Additional entries are appended for ppc64le and s390x where applicable.

Reasoning

• Upstream already publishes artifacts for amd64 and arm64, making local rebuilds unnecessary.
• Concentrating builds on architectures not covered upstream allows this repository to focus on its primary gap.
• Preserving upstream manifest entries while extending them for additional architectures maintains compatibility with existing consumers.

Impact

• Clear boundaries of responsibility between upstream and downstream.
• Lower maintenance and CI overhead.
• Predictable behavior for consumers of the version manifest.

---

Expected Outcome

A release process that is:

• Predictable for users
• Compatible with upstream behavior
• Explicit about scope, responsibility, and trade-offs
• Less likely to require frequent policy revisions

---

References (Core)

1. PEP 602 – Annual Release Cycle
   https://peps.python.org/pep-0602/
   Describes the typical cadence and lifecycle phases of Python releases.

2. PEP 387 – Backwards Compatibility Policy
   https://peps.python.org/pep-0387/
   Explains expectations around compatibility across releases, including patch releases.

3. Python Developer Guide – Versions & Status
   https://devguide.python.org/versions/
   Defines bugfix, security-only, and end-of-life status for Python versions.

4. actions/python-versions (Upstream)
   https://github.com/actions/python-versions
   Source of Python artifacts consumed by GitHub Actions.

5. actions/setup-python
   https://github.com/actions/setup-python
   Documents how Python versions and manifests are resolved in GitHub Actions workflows.