UAT: `ruff` version constraint inconsistency between `dev` and `docs` optional-dependency groups in `pyproject.toml` #4050

New issue

Open

opened 2026-04-06 09:28:51 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 09:28:51 +00:00

Owner

Metadata

Branch: fix/align-ruff-version-constraints
Commit Message: fix(build): align ruff version constraints across dev and docs dependency groups
Milestone: (none — backlog)
Parent Epic: #2810

Backlog note: This issue was discovered during autonomous UAT testing
of the Dependency Management and Package System feature area.
It does not block milestone completion and has been placed in the backlog
for human review and future milestone assignment.

Bug Report

What Was Tested

Code-level analysis of pyproject.toml optional dependency groups for version constraint consistency.

Expected Behavior

The ruff version constraint should be consistent across all optional-dependency groups that declare it. If the dev group pins a specific version range for reproducibility, the docs group should use the same or a compatible constraint.

Actual Behavior

ruff is declared with different version constraints in two optional-dependency groups:

[project.optional-dependencies]
dev = [
    # Code formatting and linting
    "ruff>=0.15.0,<0.16.0",   # Pinned to 0.15.x only
    ...
]
docs = [
    ...
    "ruff>=0.4.0",             # Much looser — allows any version >= 0.4.0
]

The dev group pins ruff to >=0.15.0,<0.16.0 (a specific minor version), while the docs group allows ruff>=0.4.0 (any version from 0.4.0 onwards, including 0.15.x, 0.16.x, and beyond).

Problems This Creates

Inconsistent behavior: A developer who installs .[dev] gets ruff 0.15.x. A developer who installs .[docs] could get ruff 0.16.x or later, which may have different formatting/linting behavior.
Potential CI failures: If the docs nox session installs .[docs] and gets a different ruff version than the lint session (which installs ruff>=0.15,<0.16 directly), the two sessions may produce different results.
The nox lint session installs ruff>=0.15,<0.16 directly (not via .[dev]), which is consistent with the dev group. But the docs group's loose constraint is still a maintenance hazard.

File Reference

pyproject.toml, lines in [project.optional-dependencies]:

dev group: "ruff>=0.15.0,<0.16.0"
docs group: "ruff>=0.4.0"

Fix

Align the ruff version constraint in the docs group with the dev group:

[project.optional-dependencies]
dev = [
    "ruff>=0.15.0,<0.16.0",
    ...
]
docs = [
    ...
    "ruff>=0.15.0,<0.16.0",  # Aligned with dev group
]

Or alternatively, if docs needs a different version for a specific reason, document why the versions differ.

Subtasks

Align ruff version constraint in docs group with dev group in pyproject.toml
Verify mkdocs and related docs tools work with the aligned ruff version
Run nox -e docs to verify no regressions

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
ruff version constraints are consistent across dev and docs groups in pyproject.toml
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/align-ruff-version-constraints` - **Commit Message**: `fix(build): align ruff version constraints across dev and docs dependency groups` - **Milestone**: *(none — backlog)* - **Parent Epic**: #2810 > **Backlog note:** This issue was discovered during autonomous UAT testing > of the Dependency Management and Package System feature area. > It does not block milestone completion and has been placed in the backlog > for human review and future milestone assignment. ## Bug Report ### What Was Tested Code-level analysis of `pyproject.toml` optional dependency groups for version constraint consistency. ### Expected Behavior The `ruff` version constraint should be consistent across all optional-dependency groups that declare it. If the `dev` group pins a specific version range for reproducibility, the `docs` group should use the same or a compatible constraint. ### Actual Behavior `ruff` is declared with **different version constraints** in two optional-dependency groups: ```toml [project.optional-dependencies] dev = [ # Code formatting and linting "ruff>=0.15.0,<0.16.0", # Pinned to 0.15.x only ... ] docs = [ ... "ruff>=0.4.0", # Much looser — allows any version >= 0.4.0 ] ``` The `dev` group pins `ruff` to `>=0.15.0,<0.16.0` (a specific minor version), while the `docs` group allows `ruff>=0.4.0` (any version from 0.4.0 onwards, including 0.15.x, 0.16.x, and beyond). ### Problems This Creates 1. **Inconsistent behavior**: A developer who installs `.[dev]` gets ruff 0.15.x. A developer who installs `.[docs]` could get ruff 0.16.x or later, which may have different formatting/linting behavior. 2. **Potential CI failures**: If the `docs` nox session installs `.[docs]` and gets a different ruff version than the `lint` session (which installs `ruff>=0.15,<0.16` directly), the two sessions may produce different results. 3. **The nox `lint` session** installs `ruff>=0.15,<0.16` directly (not via `.[dev]`), which is consistent with the `dev` group. But the `docs` group's loose constraint is still a maintenance hazard. ### File Reference `pyproject.toml`, lines in `[project.optional-dependencies]`: - `dev` group: `"ruff>=0.15.0,<0.16.0"` - `docs` group: `"ruff>=0.4.0"` ### Fix Align the `ruff` version constraint in the `docs` group with the `dev` group: ```toml [project.optional-dependencies] dev = [ "ruff>=0.15.0,<0.16.0", ... ] docs = [ ... "ruff>=0.15.0,<0.16.0", # Aligned with dev group ] ``` Or alternatively, if `docs` needs a different version for a specific reason, document why the versions differ. ## Subtasks - [ ] Align `ruff` version constraint in `docs` group with `dev` group in `pyproject.toml` - [ ] Verify `mkdocs` and related docs tools work with the aligned ruff version - [ ] Run `nox -e docs` to verify no regressions ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - `ruff` version constraints are consistent across `dev` and `docs` groups in `pyproject.toml` - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 09:29:18 +00:00

#2810 Epic: CI Quality Gates Restoration — Restore All 11 CI Jobs to Passing on Master

freemo referenced this issue

2026-04-06 09:29:44 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 09:33:49 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 10:35:53 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775