chore: add a uv, just and act dev environment next to the pip setup by winstonliu1111 · Pull Request #267 · mlcommons/chakra

winstonliu1111 · 2026-11-12T00:15:03Z

Closes #261. Part of Goal 0, #260.

What this adds

A modern dev environment next to the pip setup. Nobody has to move to uv.

just setup installs Python 3.11, the dev tools and PARAM (uv).
just gate runs the full local check: ruff, vulture, shellcheck, pyright, tests, a protobuf smoke test, a wheel check and the C++ format check.
just act <workflow> runs a GitHub workflow in Docker on your computer.
doc/DEVELOPMENT.md explains it all. README and CONTRIBUTING link to it. USER_GUIDE has an "install with uv" option.

What does not change

Item	State
`.github/` (CI workflows)	Not changed
`requirements-dev.txt`, `setup.cfg`	Not changed
pip setup and `python -m pytest tests`	Work as before. The new tooling tests that read shared files are skipped unless `CHAKRA_TOOLING_TESTS=1` is set (`just test` sets it).
The built wheel	Same contents (checked in Phase 0 and by `just wheel-check`)

pyproject.toml gets new sections at the end only. The pip dev path is removed in a later PR (#264), and only when the maintainers agree.

One code change to know

setup.py becomes setup(). The custom build_grpc class in it repeats the one that setuptools-grpc already adds, and it broke uv sync (editable install). #254 makes the same change.

Evidence

Check	Result
`just gate` in a fresh clone of this branch (macOS arm64)	exit 0: 184 passed, 2 slow passed, 0 pyright errors
`just gate` on the final commits, in a working checkout	exit 0, same counts
Old CI-style `python -m pytest tests`	passes
The 4 old pip workflows (`python_lint`, `python_tests`, `end_to_end_tests`, `cpp_lint`) under `act` (OrbStack)	pass
`just setup` and `just gate` in a WSL Debian 13 (trixie) instance	works (reported by Andy Balogh)
Rebase on current `main` (includes #259)	clean, gate passes
Scratch merge with `issue-254-linter`	merges clean. `just test` needs 2 new pins (see below). pyright reports 4 errors in its new tests.

Three independent reviews found no blockers. We took their fixes. The 9 commits are signed.

If you have an open branch

No new check runs in today's CI. Nothing here can fail an open branch in CI.
just gate is local and optional. Run it before your PR if you use the new setup.
If you add or change a dev dependency, also change [dependency-groups] dev in pyproject.toml. just test checks that it matches requirements-dev.txt. Add chakra_linter to validate Chakra execution traces against a rule set #254 adds jsonschema==4.21.1 and markdown==3.11.2. Whoever merges second adds these two pins.
Add chakra_linter to validate Chakra execution traces against a rule set #254: pyright 1.1.359 reports 4 errors in tests/linter/test_attribute_rules.py (lines 17, 84, 94) and test_timing_rules.py (line 163). The tests pass. Only the type check fails.

Not tested

Docker Desktop for just act (it works on OrbStack).
Native Windows (not supported: the scripts need bash).
Ubuntu, and Linux outside WSL.
feeder_tests.yml passes on GitHub and fails only under act
The feeder_tests.yml workflow fails under act (a Docker apt prompt). It is not part of just gate. It is planned in Run CI through the just recipes #263.

Next steps (not in this PR)

Bump tools and add uv.lock after Handle et_replay installation #237 and Add chakra_linter to validate Chakra execution traces against a rule set #254 merge (Pin the dev tools and add uv.lock #262).
Run CI through the same just recipes (Run CI through the just recipes #263).
Remove the pip dev path, when the maintainers agree (Retire the pip dev path #264).

🤖 Generated with Claude Code

setuptools-grpc already adds build_grpc to the build command through an entry point. The copy in setup.py made every editable install fail with "command 'build_grpc' has no such option 'proto_files'". So `uv sync` and `pip install -e .` failed. The wheel does not change: same files, same generated modules. Tests: a check of setup.py, and a slow test (CHAKRA_TEST_SLOW=1) that builds an editable install and imports a generated module. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Add [dependency-groups] to pyproject.toml, at the end of the file. The dev group has the same pins as requirements-dev.txt. The param group installs PARAM (et_replay) from git at the commit that CI uses. It is temporary. Ignore .venv/ and uv.lock. There is no .python-version file, on purpose. pyenv, mise and asdf read it, so it would reach people who do not use uv. A test guards this. uv rebuilds the package when a .proto file changes (cache-keys). Without this, the generated *_pb2.py files stay old after a .proto edit. requirements-dev.txt and the workflows do not change. Tests check that the two pin lists stay equal and that the PARAM commit matches CI. These tests read files that other branches change, so they run only when CHAKRA_TOOLING_TESTS=1 (`just test` sets it). The existing CI job does not set it, so an open branch does not fail. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Shell logic goes in scripts/, so it can be linted and tested alone: - run_on_git_files.sh runs a command on tracked and new files, not on ignored or deleted ones. It stops on an empty list, so a check cannot pass on nothing. A file that is not added to git yet is checked too. - proto_smoke.sh is the CI "Protobuf Gencode/Runtime Smoke Test": it imports the generated protobuf modules with the newest protobuf, then with the lowest one that pyproject.toml allows. - wheel_check.sh checks the package the way a user and CI get it. It builds a wheel from a clean copy, installs it (not editable) into a new environment, and tests it there. The other checks use the editable install that `uv sync` makes, and an editable install can hide a file that the wheel does not hold. A slow test shows this: with the .proto files left out of the package data, the editable install still works and the wheel check fails. .gitignore ignores *.pb.cc and *.pb.h, the protoc output of the C++ feeder build, so a check of new files does not see generated code. tests/test_scripts.py runs each script with fake programs first on PATH. It uses real git repositories, isolated from the git settings of the caller (a git hook sets GIT_INDEX_FILE). It needs no network, except the slow wheel test. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

`just gate` runs the checks that CI runs: ruff, vulture, pyright, the unit tests, the protobuf smoke test and clang-format 16. It also checks the Python format (`ruff format --check`), the shell scripts (shellcheck), and the built wheel (`just wheel-check`), so that both ways to install the package are tested. CI runs `ruff format .` without --check, so a format error never failed there. The justfile sets UV_PYTHON to 3.11, the version that CI uses, so uv needs no .python-version file. Also: `just test-slow`, `just fmt`, `just setup` and `just ci-github-lint` (actionlint in Docker; not part of the gate). Tests check the recipes, that CI and the justfile run the same commands, that UV_PYTHON matches the Python version of CI, and that a comment does not point to a missing file. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

`just act [workflow]` runs one workflow in Docker with act (scripts/act.sh). The script finds the Docker socket and the CPU type itself, so it works with Docker Desktop and OrbStack, on arm64 and x86_64. It tells act not to mount the Docker socket into the job. The workflows do not need it, and it is a likely fix for Docker Desktop on macOS. Before each run the script removes the shared act toolcache volume and the act containers that use it. Without this, a package that one run installed is visible to the next run, and a failed job leaves a container that holds the volume. The script refuses to start while another act run is active on this computer, and it says what it removes. It also stops if pgrep, which it needs for that check, is missing. .actrc maps ubuntu-latest to catthehacker/ubuntu:act-24.04. Ignore .secrets, .env and .vars, which act reads. Tests run the script with fake docker, act, uname and pgrep programs. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

README.md gets a short Development section: two commands, a line that the pip setup still works, and a link. doc/DEVELOPMENT.md is the developer guide: what to install, the daily steps, the recipes, the shell scripts, how to run the CI workflows with act (and which ones work), and the classic pip setup, which still works. USER_GUIDE.md gets an "install with uv" alternative for end users. Tests check that the README section stays short, that links resolve, that the docs name only recipes that exist and list every recipe, that sentences have at most 25 words (a simple Simplified Technical English check), that the docs use the PARAM commit of pyproject.toml, that the classic setup installs PARAM before it runs the tests, and that the README says the pip setup still works. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

CONTRIBUTING.md now tells contributors where the development guide is and to run `just gate` before a pull request. Tests check that the link is there and that it resolves. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

The recipes and the scripts need bash. The development guide now says to use WSL2 on Windows, that native Windows is not supported, and that the steps were tested only on macOS. A test checks that the section exists and names WSL2 and bash. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

A tester ran `just setup` and `just gate` in a WSL instance of Debian 13 (trixie). The Windows section now says what was tested, and no longer names Ubuntu, which nobody tested. The test for the Windows section checks the new wording. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

github-actions · 2026-11-12T00:15:14Z

MLCommons CLA bot All contributors have signed the MLCommons CLA ✍️ ✅

winstonliu1111 · 2026-11-12T00:45:58Z

Local check of the wheel (just wheel-check), commit 52940cc

I built a wheel from git archive of the PR head and checked it without the script. This ran on macOS arm64 with Python 3.11. CI does not run this check.

$ just wheel-check
scripts/wheel_check.sh
wheel_check: the wheel is complete and works with protobuf 6.31.1 and the newest protobuf
EXIT=0

Check	Result
Generated modules in the wheel	`et_def_pb2.py`, `storage_pb2.py`, `et_def_pb2_grpc.py`, `storage_pb2_grpc.py`, and both `.pyi` files
`.proto` files in the wheel	`chakra/schema/protobuf/et_def.proto`, `storage.proto`
Lowest protobuf (6.31.1)	Imports from `site-packages`. A message round trip returns the right value.
Newest protobuf (7.36.2, allowed by `<8`)	Same result
Commands	`chakra_converter` exits 0. The other three exit 2 (they need arguments).
Metadata	`Requires-Python: >=3.11`, `Requires-Dist: protobuf<8,>=6.31.1`, 0 git or URL dependencies

Limits: this tests import, a message round trip and command start. It is not a functional test of the converter. It does not cover other platforms or Python versions. The CI clean-install job covers 3.11, 3.12 and 3.13.

winstonliu1111 · 2026-11-12T00:47:43Z

also, will tick off the merge criteria in the issue:

main: the branch is rebased on the current main. GitHub shows the PR as mergeable.
#254: the scratch merge of 1279765 had no conflicts. It also has two side effects that the box does not cover: 2 pin changes needed for just test, and 4 pyright errors in its tests. Keep both in the PR text, as they are now.

winstonliu1111 · 2026-11-12T00:50:20Z

local "act" tests ran against orbstack... I don't have docker desktop, so can't test there. will tick off the "just act python_lint.yml passes on Docker Desktop. Evidence: tester report. (It passes on OrbStack.)" in #261

winstonliu1111 and others added 9 commits November 11, 2026 16:09

docs: link the development guide from CONTRIBUTING.md

7573232

CONTRIBUTING.md now tells contributors where the development guide is and to run `just gate` before a pull request. Tests check that the link is there and that it resolves. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

winstonliu1111 requested review from ajbalogh, briancoutinho, danmih-ixia, jinsun-yoo and theodorbadea November 12, 2026 00:15

ajbalogh approved these changes Nov 12, 2026

View reviewed changes

winstonliu1111 requested a review from HanjiangWu313 November 12, 2026 18:12

ajbalogh merged commit 2d76d5b into mlcommons:main Nov 12, 2026
13 checks passed

winstonliu1111 deleted the chore/dev-env-modernization branch November 13, 2026 01:11

Navigation Menu

Repository navigation

chore: add a uv, just and act dev environment next to the pip setup - #267

chore: add a uv, just and act dev environment next to the pip setup#267
ajbalogh merged 9 commits into
mlcommons:mainfrom
Keysight:chore/dev-env-modernization

winstonliu1111 commented Nov 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Nov 12, 2026

Uh oh!

winstonliu1111 commented Nov 12, 2026

Uh oh!

winstonliu1111 commented Nov 12, 2026

Uh oh!

winstonliu1111 commented Nov 12, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

winstonliu1111 commented Nov 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this adds

What does not change

One code change to know

Evidence

If you have an open branch

Not tested

Next steps (not in this PR)

Uh oh!

github-actions Bot commented Nov 12, 2026

Uh oh!

winstonliu1111 commented Nov 12, 2026

Uh oh!

winstonliu1111 commented Nov 12, 2026

Uh oh!

winstonliu1111 commented Nov 12, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

winstonliu1111 commented Nov 12, 2026 •

edited

Loading