From 97132e1a3e7481b4912d2f777b43b53a230583a7 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Fri, 28 Aug 2026 11:51:01 +0530 Subject: [PATCH] ci: validate Click 8.3 and 8.4 compatibility (#237) --- .github/workflows/dependency-matrix.yml | 2 +- CHANGELOG.md | 2 ++ docs/api-stability.md | 7 ++++--- docs/dependency-support.md | 6 ++++-- docs/platform-support.md | 3 ++- pyproject.toml | 2 +- scripts/validate_package_artifact.py | 2 +- 7 files changed, 15 insertions(+), 9 deletions(-) diff --git a/.github/workflows/dependency-matrix.yml b/.github/workflows/dependency-matrix.yml index cbac924..ec6b530 100644 --- a/.github/workflows/dependency-matrix.yml +++ b/.github/workflows/dependency-matrix.yml @@ -20,7 +20,7 @@ jobs: fail-fast: false matrix: python-version: ["3.10", "3.14"] - click-version: ["8.1.*", "8.2.*"] + click-version: ["8.1.*", "8.2.*", "8.3.*", "8.4.*"] pyyaml-version: ["6.0.*"] steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 8716a27..90e0ee5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ and versions are tracked in the repo-root `VERSION` file. modules without changing the public import surface. - Bound the core Click and PyYAML dependency windows, publish the tested compatibility matrix, and document the dependency update policy. +- Validate Click 8.1 through 8.4 on the supported Python floor and ceiling, + and reject unvalidated Click 8.5+ versions through package metadata. - Move PyYAML behind the optional `base-cli[yaml]` extra and provide an actionable installation hint when YAML configuration or output is selected. - Add an explicit `App.async_command()` adapter and `run_async()` helper for diff --git a/docs/api-stability.md b/docs/api-stability.md index 367ebae..3b2ad5c 100644 --- a/docs/api-stability.md +++ b/docs/api-stability.md @@ -49,12 +49,13 @@ that need a frozen API should pin a minor release (for example, `~=0.4.0`). The core package requires Python `>=3.10` and currently tests CPython 3.10 through 3.14 on Linux, macOS, and Windows. The core runtime dependency is -Click `>=8.1,<9`; YAML configuration and YAML output are provided by the +Click `>=8.1,<8.5`; the compatibility suite covers the 8.1, 8.2, 8.3, and +8.4 lines on Python 3.10 and 3.14. YAML configuration and YAML output are provided by the optional `base-cli[yaml]` extra, which supplies PyYAML `>=6.0,<7`. Other optional integrations are independently versioned and constrained in `pyproject.toml`: Typer `>=0.12,<0.28`, Rich `>=13.7,<15`, and OpenTelemetry API `>=1.24,<2`. The -lower bounds are the minimum supported versions; a dependency major release -is supported only after it passes the compatibility suite. The tested core +lower bounds are the minimum supported versions; a dependency minor or major +release is supported only after it passes the compatibility suite. The tested core dependency matrix is maintained in [`dependency-support.md`](dependency-support.md). A future minor release may drop an end-of-life Python or dependency window with a migration note. diff --git a/docs/dependency-support.md b/docs/dependency-support.md index 321e4d2..17a7a88 100644 --- a/docs/dependency-support.md +++ b/docs/dependency-support.md @@ -9,7 +9,7 @@ documents the versions covered by CI and the process for widening a window. | Dependency | Declared window | CI coverage | Policy | | --- | --- | --- | --- | | Python | `>=3.10,<4` (CPython 3.10--3.14) | Every OS test job | Drop an end-of-life line only in a documented compatibility release | -| Click | `>=8.1,<9` | 8.1 and 8.2 lines on Python 3.10 and 3.14 | Review the next major before widening the upper bound | +| Click | `>=8.1,<8.5` | 8.1, 8.2, 8.3, and 8.4 lines on Python 3.10 and 3.14 | Add a matrix lane and compatibility note before widening the upper bound | | YAML extra | `PyYAML>=6.0,<7` | 6.0 line on Python 3.10 and 3.14 | Install `base-cli[yaml]`; keep parser behavior covered by profile tests | The `base-cli[yaml]` extra is the minimal installation for YAML profiles. @@ -27,7 +27,9 @@ Optional integrations are intentionally independent of the core window: ## Updating a window -1. Add the candidate lower or upper line to the dependency matrix. +1. Add the candidate lower or upper line to the dependency matrix. The + current supported Click window is 8.1 through 8.4; versions outside that + window are rejected by package metadata until they are evaluated. 2. Run the full test, type-check, documentation, and installed-wheel gates. 3. Review release notes and consumer impact, including resolver behavior. 4. Update `pyproject.toml`, this page, and the API stability contract in one diff --git a/docs/platform-support.md b/docs/platform-support.md index a3ceebe..677b6ac 100644 --- a/docs/platform-support.md +++ b/docs/platform-support.md @@ -36,7 +36,8 @@ filesystem. ## Dependency support -The core runtime dependency contract is Click `>=8.1,<9`. YAML configuration +The core runtime dependency contract is Click `>=8.1,<8.5`, tested across the +8.1 through 8.4 lines. YAML configuration and YAML output use the optional `base-cli[yaml]` extra, which supplies PyYAML `>=6.0,<7`. The lower bound is the oldest supported line; the upper bound prevents an unreviewed major release from entering a production install. The diff --git a/pyproject.toml b/pyproject.toml index 1e8264b..003ed14 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -47,7 +47,7 @@ classifiers = [ "Topic :: System :: Shells", ] dependencies = [ - "click>=8.1,<9", + "click>=8.1,<8.5", ] [project.optional-dependencies] diff --git a/scripts/validate_package_artifact.py b/scripts/validate_package_artifact.py index 6e2020c..020d4cc 100644 --- a/scripts/validate_package_artifact.py +++ b/scripts/validate_package_artifact.py @@ -15,7 +15,7 @@ PACKAGE_NAME = "base-cli" IMPORT_NAME = "base_cli" MINIMUM_PYTHON = ">=3.10" -REQUIRED_DEPENDENCIES = ("click<9,>=8.1",) +REQUIRED_DEPENDENCIES = ("click<8.5,>=8.1",) YAML_DEPENDENCY_PREFIX = "PyYAML<7,>=6.0" DOCUMENTATION_URL = "Documentation, https://basefoundry.github.io/base-cli/" ALLOWED_WHEEL_DIST_INFO_FILES = frozenset({"METADATA", "RECORD", "WHEEL", "top_level.txt", "entry_points.txt"})