ci: validate Click 8.3 and 8.4 compatibility (#237)

.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

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

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.

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

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

pyproject.toml

@@ -47,7 +47,7 @@ classifiers = [
   "Topic :: System :: Shells",
 ]
 dependencies = [
-  "click>=8.1,<9",
+  "click>=8.1,<8.5",
 ]
 
 [project.optional-dependencies]

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"})