docs: make CLAUDE.md and CONTRIBUTING.md agree, and each own its facts - #490
Merged
Conversation
Follow-up to #489. That PR made `ruff format --check .` a CI gate alongside `ruff check .`, but nothing wrote the convention down, so the next agent would have gone on assuming a clean `ruff check .` meant the lint job would pass. - Code Quality: state that the gate is two independent commands, that the ruff-pre-commit rev must track the ruff pin in pyproject.toml, and how to handle a `# noqa` stranded by a reflow (move it, do not delete it). - CI/CD: the run-tests.yml description still listed `lint` as `ruff check .` alone, which is now wrong. No version bump: CLAUDE.md is agent instructions rather than shipped code or configuration, and this file already classes edits to itself as internal-only. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MT8LQS1YtrAGzir5SUeqWD
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Each of these sends a new contributor somewhere the repository no longer is: - Setup said `pip install -e ".[dev]"`, which omits the optional runtime dependencies. pyDOE3 lives in the `expt`/`all` extras, so that environment fails a large part of the suite on ImportError rather than skipping. Now `".[dev,all]"`, matching CI's `uv sync --dev --all-extras`. - The lint block told contributors to run `black .`, which is configured nowhere in the repository and contradicts the ruff-only policy, and `mypy process_improve`, which is the wrong path under the src layout. It now also documents `ruff format --check .` as the second, independent gate added in #489, and the pre-commit rev/pin alignment that gate depends on. - "Adding new methods" pointed at `multivariate/methods.py`, which has been a re-export shim since ENG-01; a method added there has no effect. Now points at `_pca.py` / `_pls.py` and names the sibling modules. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MT8LQS1YtrAGzir5SUeqWD
The file was accurate but was acting as a parallel contributor guide: it referenced none of the repository's other authoritative documents, restated policy that CONTRIBUTING.md owns, and carried reference data that duplicates the source and had already gone stale in one place. Removed, because the code or CONTRIBUTING.md is the better source: - The PCA and PLS fitted-attribute lists. They duplicated each class's Attributes docstring and had already drifted; PCA sets `algorithm_`, which the list omitted. Replaced with a pointer to read the class. - The `_model_method` code snippet. The rule and its rationale are kept; an agent editing that class reads the real code anyway. - Long-form Docstrings, Scaling and "Adding New Methods to PCA/PLS" sections that CONTRIBUTING.md already covers. One-line rules stay so common cases do not need a second file open. Added, because nothing pointed at them: - An Authoritative documents table: CONTRIBUTING.md plus the five policy documents under docs/development/ (error handling, reproducibility, deprecation, logging, tool authoring) and SKLEARN_COMPATIBILITY.md. - Test tier markers. pytest.ini registers unit/integration/slow/dataset, and an untagged slow or network-bound test silently breaks `-m 'not slow'`. - `Expt` and the `pi_` metadata prefix, a public-API convention the file did not mention at all. - MAJOR in the versioning list. The section defined only PATCH and MINOR, then asked the reader to decide whether a change was "major or minor" using a word it never defined, and never mentioned the deprecation schedule. - The `_LazyFrame` descriptor (ENG-18). Seven fitted attributes are descriptors over a private ndarray, so the "set only in fit()" rule alone would mislead anyone adding one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MT8LQS1YtrAGzir5SUeqWD
kgdunn
changed the title
kgdunn
added a commit
that referenced
this pull request
Aug 10, 2026
The branch was cut from 0e8e8d1 on 7 August, before #486 through #490 merged, and had gone stale. Four files conflicted. Version metadata. This branch set 1.63.0 in pyproject.toml and CITATION.cff, but 1.63.0 was released from main on 8 August by #486, and main now stands at 1.66.1. Taking this branch's value would have moved the version backwards onto a number already in use, so main's 1.66.1 is kept in both files and no bump is made here. CHANGELOG. The "## [1.63.0] - 2026-08-07" heading is dropped for the same reason and its body moves under [Unreleased], leaving main's released history untouched. The link-reference footer is taken from main, which carries the four releases this branch predates. experiments/__init__.py. Both sides appended to __all__ in the same region: this branch added moment_aberration, main added manufacture and omars_minimum_runs. All three are kept, alphabetical order restored, and the list checked programmatically against the module's imports. evaluate.py merged without conflict. One thing the merge could not flag. SKILL.md stated that ten @tool_spec DOE tools are reachable through the dispatcher and listed them in a table. Main added an eleventh, trade_off_table, in #487. The count and the table are corrected, and the documented list is now checked against the modules actually present in experiments/_tools. Verification after the merge: ruff check . and ruff format --check . clean mypy src/process_improve clean, 146 source files pytest: 2530 passed, 5 skipped, coverage 94.12% moment_aberration still reproduces the paper's Table 1 pattern exactly (3.27, 11.67, 42.47, 157.27, 591.27, 2251.67, 8666.47) at resolution IV, both directly and through the evaluate_design metric all three skill scripts run, including the non-zero exit path: verify_design.py --require-resolution 5 exits 3 on a resolution IV design Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01W1daHPaXLs7PPRsq8CmMMm
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Started as the follow-up to #489 (record the two-command lint gate in
CLAUDE.md), then grew to cover the reason that gate went unrecorded in the first place: the two contributor-facing documents had drifted apart, and neither pointed at the other.Three commits.
1. Record the lint gate in
CLAUDE.mdThe gate is two independent commands; the
ruff-pre-commitrev must track theruffpin; and a# noqastranded by a reflow should be moved, not deleted. That last one was the only non-mechanical part of #489: four directives sat at the end of long lines the reflow split, so each stayed behind while the code it suppressed moved. Ruff then reports both the unsuppressed rule and the unused directive, and the tempting fix (delete theRUF100) silently drops a live suppression.2. Correct three stale instructions in
CONTRIBUTING.mdEach sends a new contributor somewhere the repository no longer is:
pip install -e ".[dev]"pyDOE3is inexpt/all, so a large part of the suite fails onImportErrorrather than skipping. Now".[dev,all]", matching CI'suv sync --dev --all-extras.black .ruff format ., plusruff format --check .as the second gate from #489.mypy process_improvemypy src/process_improve.multivariate/methods.py"methods.pyhas been a re-export shim since ENG-01, so a method added there has no effect. Now points at_pca.py/_pls.py.The first one is not theoretical: following that setup line in this session produced 130 failing tests before I matched CI's install.
3. Restructure
CLAUDE.mdaround single sources of truthIt was accurate, but acting as a parallel contributor guide: it referenced none of the repo's other authoritative documents, restated policy
CONTRIBUTING.mdowns, and carried reference data duplicating the source.Removed (code or
CONTRIBUTING.mdis the better source): the PCA/PLS fitted-attribute lists, which duplicated each class'sAttributesdocstring and had already drifted (PCA setsalgorithm_, which the list omitted); the_model_methodsnippet, keeping the rule and rationale; and the long-form Docstrings / Scaling / "Adding New Methods" sections. One-line rules stay, so common cases do not need a second file open.Added (nothing pointed at these):
CONTRIBUTING.md, the five policy docs underdocs/development/(error handling, reproducibility, deprecation, logging, tool authoring), andSKLEARN_COMPATIBILITY.md.pytest.iniregistersunit/integration/slow/dataset; an untagged slow or network-bound test silently breaks-m 'not slow'for everyone.Exptand thepi_prefix, a public-API convention the file did not mention at all._LazyFrame(ENG-18). Seven fitted attributes are descriptors over a private ndarray, so the "set only infit()" rule alone would mislead anyone adding one.Test plan
ruff check .andruff format --check .both passCONTRIBUTING.mdanchor linked fromCLAUDE.mdmatches a real headingmethods.pyshim,_LazyFramesemantics,Expt/pi_*attributes,pytest.inimarkers, and thatblackappears in no config fileChecklist
pyproject.toml- not bumped, per maintainer instruction on this PR. Both files are contributor documentation and neither is packaged.ruff check .passesCHANGELOG.mdupdated - not required:CLAUDE.mdclasses edits to itself as internal-only, and theCONTRIBUTING.mdcorrections are not user-facing.