Skip to content

Modernize CI: uv lock file, Dependabot, lowest-dependency testing, workflow hardening - #805

Merged
milton-minervino merged 10 commits into
MAIF:developfrom
milton-minervino:feature/modern-ci
Oct 21, 2026
Merged

milton-minervino merged 10 commits into
MAIF:developfrom
milton-minervino:feature/modern-ci

Conversation

@milton-minervino

@milton-minervino milton-minervino commented Oct 20, 2026 •

Copy link
Copy Markdown
Collaborator

Description

CI used to install the newest dependencies with pip on every run. A new release anywhere in the stack could break an unrelated PR, and nothing checked the lower bounds declared in pyproject.toml. This PR pins CI to a committed uv.lock, adds Dependabot to keep that lock current, tests the declared lower bounds, hardens the workflows, and updates the contributing guide to match.

Dependencies and lock file

  • uv.lock committed: the test and code-quality jobs install exactly these versions (uv sync --locked fails when the lock is out of date), so CI results are reproducible.

  • exclude-newer = "7 days" in [tool.uv]: releases younger than a week are ignored, as a supply-chain cooldown. It needs uv >= 0.9.17, enforced with required-version.

  • Lower bounds raised: the new lowest_deps job showed that several declared lower bounds never worked:

    Dependency Old New Failure at the old bound
    category_encoders 2.6.0 2.8.0 uses the removed scikit-learn _get_tags (262 failing tests)
    panel (report) 1.8.10 1.9.0 widgets reject the label= argument (11 failing tests)
    Flask 1.0.4 2.3.0 Markup import error with current Jinja2
    plotly 5.0.0 5.12.0 uses np.bool8, removed from numpy
    shapely 2.0.0 2.0.4 built against numpy 1
    shap 0.46.0 0.50.0 can't read models from xgboost >= 3.1
  • Caps removed: requires-python (<3.15) and scikit-learn (<1.10). Upper caps on a library block users' installs before any problem exists. The dash, plotly and pandas caps stay, because their major releases have broken shapash before.

  • wheel removed from build-system.requires, since setuptools no longer needs it.

  • pytest>=8.0 and pytest-cov>=6.0 floors added to the test group; zizmor added to dev.

Dependabot (.github/dependabot.yml, new)

  • uv ecosystem, weekly, targeting develop:
    • Minor and patch releases are grouped into one PR.
    • Each major release gets its own PR.
    • versioning-strategy: widen only edits pyproject.toml to raise an upper cap, so a major dash, plotly or pandas release arrives as a PR that tests the new major.
  • GitHub Actions ecosystem, weekly and grouped.
  • Both use a 7-day cooldown, matching exclude-newer.

CI (main.yml)

  • pip replaced with uv, through astral-sh/setup-uv, with the cache keyed on uv.lock.
  • Test matrix (3.11–3.14):
    • It installs the full suite, NLP included, from uv.lock via a constraints file.
    • --torch-backend cpu installs the same torch version as the lock, from the CPU-only index. This avoids several GB of CUDA libraries the tests never use.
    • The lock itself keeps the default torch wheel, so developers with a GPU are unaffected.
  • lowest_deps job replaces pandas_compat:
    • It installs every direct dependency at the lower bound in pyproject.toml (--resolution lowest-direct), on Python 3.11, without NLP.
    • A PR that relies on a newer API fails here until it raises the bound.
    • It also checks that a classical install works without torch.
  • Code quality:
    • The job now runs on Python 3.11, the oldest supported version. mypy checks against the installed libraries' type stubs, which depend on the interpreter, so code that only works on newer Pythons fails here.
    • A new make workflows step audits the workflows with zizmor.
  • workflow_dispatch added, so CI can be run manually.

Workflow hardening (all workflows)

  • Every third-party action is pinned to a commit SHA, with the version in a comment. Dependabot updates both.
  • permissions: contents: read at the top of every workflow, and persist-credentials: false on every checkout.
  • Release workflows build with uv build.
  • Release-candidate smoke test:
    • The old command used --extra-index-url and pulled dependencies from TestPyPI as well as PyPI. Anyone can upload to TestPyPI, so this was a dependency-confusion risk.
    • The new version installs only shapash from TestPyPI (--no-deps) and its dependencies from PyPI.
  • SonarQube is skipped on Dependabot PRs: they don't receive the repository secrets, so the job failed every time.

Pre-commit

  • ruff and mypy now run as local hooks, using the .venv tools that uv.lock pins.
    • Before, the ruff hook pinned its own version (0.15.20) while the lock had its own, so local hooks and CI could disagree.
    • The hooks look in .venv/bin (Linux, macOS) and .venv/Scripts (Windows), so they work without an activated venv, from the terminal or an IDE.
    • They don't require uv: any virtual environment with the dev group installed works.
  • The fragile multi-fallback mypy entry is replaced by the same pattern as the ruff hooks.

Makefile

  • New workflows target (zizmor).
  • dist builds with uv build instead of the deprecated python setup.py.
  • Dead targets removed: release (manual twine upload, replaced by the tag-triggered publish workflows), servedocs (needed watchdog, which no dependency group installs) and install.
  • Cleanup: the Python 2 browser helper is replaced by python -m webbrowser, .PHONY lists every target, the clean targets skip .venv, and clean-test also removes the mypy and ruff caches.

CONTRIBUTING.md (rewritten)

The guide is restructured for external contributors: open an issue, set up the environment, make the changes, submit them. Main changes:

  • uv is the recommended setup, with pip as an alternative, and the NLP extra is explained.
  • The commands are the make targets CI runs, with notes for contributors without make.
  • Coverage expectations: the run fails below 75% total, and Codecov requires 90% coverage of the lines a PR adds or changes.
  • New sections: changing dependencies (lock file, lowest-deps job), updating docs and tutorials, review and merge.
  • New "Contributing using AI" section: we adopt the unitaryHACK AI guide, summed up for shapash.

Type of change

  • CI / tooling (no change to the library code)
  • This change requires a documentation update (CONTRIBUTING.md, included)

How Has This Been Tested?

  • Lowest dependencies: unit suite at the new lower bounds, 1823 passed and 4 skipped; integration tests, 12 passed and 4 skipped.
  • mypy on Python 3.11 against the locked environment: no issues. On 3.13 with --python-version 3.11, it fails on numpy's stubs, which is why the job runs on 3.11.
  • zizmor: no findings on the workflows.
  • Pre-commit: every hook passes with a minimal environment (env -i PATH=/usr/bin:/bin), which confirms the .venv lookup works.
  • Windows pre-commit hooks: not tested on a Windows machine.
  • The workflows themselves run for the first time on this PR. The release workflows only run on a tag.

Test Configuration:

  • OS: Linux
  • Python version: 3.11 (lowest deps, mypy), 3.13 (default dev environment)
  • Shapash version: develop

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works (N/A: CI change)
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published in downstream modules

Use the versions pinned in uv.lock, the same ones as CI, instead of a
separately pinned ruff hook. The hooks find the tools in .venv on Linux,
macOS and Windows without an activated virtual environment.
Lock every extra and dependency group in uv.lock, which CI installs from.
Ignore releases younger than 7 days (exclude-newer) as a supply-chain cooldown.

Raise lower bounds that never worked, found by testing at the lowest
versions: category_encoders 2.8.0, panel 1.9.0, Flask 2.3.0, plotly 5.12.0,
shapely 2.0.4. Drop the requires-python and scikit-learn upper caps and the
unneeded wheel build requirement. Add zizmor to the dev group.
Add a workflows target (zizmor). Build with uv build instead of setup.py.
Remove dead targets (release, servedocs, install) and the Python 2 browser helper, list every target in .PHONY, keep the clean targets out of .venv.
Switch CI from pip to uv. Tests install the uv.lock versions, with CPU-only
torch. Replace pandas_compat with a lowest_deps job that runs the suite with every direct dependency at its lower bound. Run code quality on Python 3.11 so mypy checks against the oldest supported version, an audit the workflows with zizmor. Pin actions to commit SHAs and restrict permissions.
Pin actions to commit SHAs, restrict permissions to contents: read and stop
persisting checkout credentials. Build with uv build. Install only shapash from TestPyPI in the release-candidate smoke test and its dependencies from PyPI, to avoid dependency confusion. Skip SonarQube on Dependabot PRs, which get no secrets.
Weekly PRs targeting develop: minor and patch updates grouped in one PR, major updates in their own, with a 7-day cooldown matching exclude-newer.
Document the uv setup (pip as an alternative), the make targets CI runs, the 75% total and 90% patch coverage requirements, dependency changes, docs and tutorials, and the review process. Add a section on contributing using AI.
shap 0.49 cannot parse models from xgboost >= 3.1, so ShapBackend fell back to a generic explainer without a masker and raised "masker cannot be None". The universal lock had resolved shap 0.49.1 for Python 3.11.
@codecov

codecov Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.08%. Comparing base (938be9e) to head (9717ea4).

Additional details and impacted files
@@           Coverage Diff            @@
##           develop     #805   +/-   ##
========================================
  Coverage    86.08%   86.08%           
========================================
  Files          115      115           
  Lines        11825    11825           
  Branches      2158     2158           
========================================
  Hits         10180    10180           
  Misses        1009     1009           
  Partials       636      636           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

sleep 30
done
# Already installed, so pip keeps it and installs its dependencies from PyPI.
pip install "shapash==${RELEASE_VERSION}"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this works?
You target pypi.org here where REALESE_VERSION does not exists.
How can it fetch its dependencies?
Am I misreading something?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When shapash==X is already installed (here the release candidate from test.pypi), pip's resolver takes the installed copy ("Requirement already satisfied"). It doesn't need that version to exist on PyPI. It reads the installed package's metadata and fetches only its dependencies from PyPI.

steps:
- name: Git checkout
uses: actions/checkout@v6
uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it best pratice to target a commit hash instead of a tag?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it's the practice GitHub recommends in its security hardening guide for Actions: pinning to a full-length commit SHA is the only way to reference an action immutably.

A tag like v4 is a movable pointer. Whoever controls the action's repo (or an attacker who compromises it) can repoint the tag to different code, and our workflows would run it on the next trigger with no change on our side. A SHA, on the contrary can't be moved.

Respond to the eMudhra/emSign CA certificate security incident: certifi
2026.10.19 drops the compromised root, and uv < 0.13.4 still trusts it.

certifi is let in ahead of the 7-day cooldown through a one-off
exclude-newer-package cutoff, to be removed after 2026-10-27.
@milton-minervino
milton-minervino merged commit bf51cd2 into MAIF:develop Oct 21, 2026
9 checks passed
@milton-minervino
milton-minervino deleted the feature/modern-ci branch October 21, 2026 16:11
milton-minervino added a commit that referenced this pull request Oct 23, 2026
Dependabot rejected the config after #805: the uv ecosystem does not
accept `widen`. `auto` widens for a package detected as a library, so it
still raises upper caps and leaves the lower bounds tested by
`lowest_deps` untouched.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants