Development¶
The single entry point for working on pain001-loader-mt101: toolchain,
how to reproduce every CI gate locally, where tests live, and how a
release happens. CONTRIBUTING.md covers the etiquette
(DCO, commit format, review); this file covers the mechanics.
Toolchain¶
Tool |
Version |
Where it is pinned |
|---|---|---|
Python |
3.11 is the floor; CI tests 3.11 to 3.14 |
|
Python packages |
exact, with hashes |
|
Node |
any current LTS |
only for |
vhs |
any |
only for |
git clone https://github.com/sebastienrousseau/pain001-loader-mt101
cd pain001-loader-mt101
make install # .venv from requirements/test.txt and lint.txt
make check # every gate a pull request runs, see below
pre-commit install # optional: ruff, codespell, markdownlint on commit
make install installs the test and lint trees. The other gates need
their own hash-pinned file installed into .venv first, for example
.venv/bin/python -m pip install --require-hashes -r requirements/docs.txt.
Install them one file at a time: the files pin different versions of
some shared packages and conflict when installed together.
The devcontainer runs
make install && make check when it is created, in a Codespace or a VS
Code container.
Reproducing every CI gate¶
Gate |
Local command |
CI workflow |
|---|---|---|
Ruff lint and format |
|
|
mypy |
|
|
Complexity: cyclomatic 10, cognitive 15, Halstead 30, 60 lines per function, 500 per file, against |
|
|
Version agreement across every restatement |
|
|
Tests, 100% line and branch coverage of the package and |
|
|
100% docstring coverage |
|
|
Examples run end to end |
|
|
Benchmark still runs |
|
|
Dependency advisories over every |
|
|
Spelling and Markdown style |
|
|
Sphinx manual, warnings are errors |
|
|
Relative links and anchors in every Markdown file |
|
|
Atheris fuzzing of |
|
|
Mutation score of the parser, floor 88% |
|
|
DCO sign-off on every commit |
|
|
CodeQL, OpenSSF Scorecard |
none locally |
|
Every suite publication agrees |
none locally; the core’s |
|
make check runs lint, typecheck, complexity, verify-versions, test,
docstrings and examples, in that order, and is what a pull request must
pass before review.
Why the coverage floor is 100%¶
The package is one parser of a few hundred lines, and the branches a
test suite tends to miss are the malformed-input ones, which is exactly
where a parser that feeds payment files has to be right. scripts/ is
held to the same floor because those scripts decide whether a release
goes out. Coverage is measured with branches (--cov-branch); the scope
and the floor live in pyproject.toml’s pytest addopts, so make test
and CI cannot measure different things. The one # pragma: no cover is
the command-line guard of scripts/release_notes.py, which is vendored
byte-identical from the core; the other scripts’ entry points are run by
their tests.
Test layout¶
tests/
test_loader.py the parser: grammar, field mapping, strictness
test_fuzz.py Hypothesis properties, and a replay of fuzz/corpus/
test_benchmarks.py pytest-benchmark timings and the scaling guard
test_examples.py every script in examples/ runs and prints its result
test_readme_template.py README heading order, badges, demo, no {{...}} left,
the Quick Start executed
test_docs_links.py every relative link and #anchor in the Markdown resolves
test_verify_versions.py scripts/verify_versions.py, one drift at a time
test_check_complexity.py scripts/check_complexity.py and its baseline ratchet
test_mutation_gate.py scripts/mutation_gate.py
test_release_notes.py scripts/release_notes.py (vendored from pain001)
test_suite_conformance.py the family-wide rules; vendored byte-identical, do not edit
examples/ numbered, runnable scripts
benches/ throughput as a message grows
fuzz/ the Atheris harness and its corpus; fixed-bug inputs
are named regression-*.mt101
A fixed bug gets a regression test in tests/test_loader.py and, when
the input came from fuzzing, a regression-*.mt101 file in
fuzz/corpus/, which tests/test_fuzz.py replays on every run.
Documentation¶
Sphinx with MyST under docs/, the only documentation root. make docs
builds docs/_build/html with warnings as errors; docs.yml deploys it
to GitHub Pages from main. Root Markdown files (README.md,
ARCHITECTURE.md, this file, CHANGELOG.md) are included into the
manual by thin chapter files under docs/, so each is edited in one
place. The API reference (docs/api.md) is generated from docstrings,
which make docstrings holds at 100%. tests/test_docs_links.py fails
a pull request whose Markdown links to a file or heading that does not
exist; external URLs are not fetched, so a third-party outage cannot
fail the build. Decisions that will be questioned
later get an ADR in docs/adr/.
Versioning and release¶
The version is
0.0.x, moves by0.0.1, and every member of the pain001 suite ships the same number. The maintainer decides when a release opens; a change never bumps it on the side.It is restated in
pyproject.toml,pain001_loader_mt101/__init__.py,CITATION.cff, theSECURITY.mdandSUPPORT.mdsupport tables, the README’s latest-release callout,releases/v0.0.N.mdand a## [0.0.N]heading inCHANGELOG.md;make verify-versionschecks the ones it can.Work for the next version happens on
feat/v<next-version>, the only pull request intomain.Releases are cut from a signed tag;
release.ymlbuilds, attests, signs and publishes to PyPI with trusted publishing. RELEASING.md is the checklist.