Contributing
Development setup
Install the package from a checkout (see Installation) with the
dev extra, which adds the test and lint tools, and install the
pre-commit hooks:
pip install -e ".[dev]" -c setup/constraints/core-py310-torch2.9.1.txt
pre-commit install
Several checkouts
An editable install serves the one checkout it was installed from. When you
work with several checkouts or worktrees, run Python with
PYTHONPATH=<checkout>/src so that the code you edit is the code that
runs, for example
PYTHONPATH=$PWD/src python -m dendritic_modeling.scripts.training.train_experiments <config>.
Every training run records the imported package path and its commit in
runtime_environment.json.
Where code belongs
The library holds components that serve more than one study: models, layers,
synapse and connectivity policies, training rules, datasets, analysis tools,
configuration schemas and the command-line programs, under
src/dendritic_modeling, with tests in tests/ and documentation in
docs/. Runners, sweeps, figure scripts and configurations of one study
belong in that study’s own repository, which records the library revision it
uses.
Keep generated runs, checkpoints, datasets, logs and local credentials out of
Git. Use outputs/, data/, checkpoints/, slurm_jobs/ or jobs/
for generated files, configs/local/ for machine-specific configurations,
and scripts/local/ for ad hoc launchers. The repository’s ignore rules
exclude these locations, build products and local editor or agent state.
Maintained scripts, example configurations and small test fixtures belong in
version control. An ignore rule does not remove a file already tracked by
Git; review the staged diff before committing.
A new option or component:
is a typed configuration field with validation, so the loader accepts and checks it (see Configuration guide);
is off by default: existing configurations keep their exact behaviour, and a test shows that the default output does not change;
registers through the existing registries where one exists (see Extension registries);
is documented on the page of its topic, with an entry in
CHANGELOG.mdfor user-visible changes.
A change of what an omitted key means, such as a new default, changes the
configuration format: increment CONFIG_VERSION
(Configuration format version), add a rule to dendritic-upgrade-config that
writes the earlier meaning into files of earlier versions, and update the
shipped configurations.
Code style
black formats the code and
isort orders the imports (both configured
in pyproject.toml); ruff lints it
(configured in ruff.toml). The pre-commit hooks run all three, check
whitespace, YAML syntax, file sizes and merge markers, and run
tests/test_training_stability_validator.py. Run them on the files you
changed:
pre-commit run --files <changed files>
Fix lint warnings instead of suppressing them with # noqa; the few
existing suppressions are re-exports and benchmark lambdas.
Tests
Run the tests from the repository root with PYTHONPATH pointing at the
checkout under test:
# quick run without the slow tests
PYTHONPATH=$PWD/src python -m pytest -m "not slow" -n auto
# full suite, in parallel (pytest-xdist is in the test extra)
PYTHONPATH=$PWD/src python -m pytest -n auto
# one file
PYTHONPATH=$PWD/src python -m pytest tests/test_config.py -q
pytest.ini runs with --strict-markers and defines four markers:
slowLong tests, including tests that spawn worker processes or run training launchers; deselect them with
-m "not slow".multiprocessTests that spawn worker processes (distributed tests).
requires_gpuTests that need CUDA. Tests parametrized with
device="cuda"get the marker automatically, and hosts without CUDA skip them. The continuous integration has no GPU, so runpython -m pytest -m requires_gpuon a GPU machine before merging changes to kernels or device code.requires_git_checkoutTests that read the library’s own Git checkout (its commit and tracked files); they are skipped when the tests run from a source archive or sdist.
The continuous integration also measures coverage; to reproduce that check:
PYTHONPATH=$PWD/src python -m pytest tests/ -n 2 \
--cov=src/dendritic_modeling --cov-branch \
--cov-report=xml --cov-fail-under=30
tests/README.md describes the default-path golden tests, which fail when
a change alters the default behaviour, and how to regenerate their fixture.
Building the documentation
pip install -e ".[docs]"
python -m sphinx -b html -W --keep-going docs docs/_build/html
-W turns warnings into errors; the pages build without warnings, and the
pull-request checks and the documentation deployment build them with the same
command. Open
docs/_build/html/index.html to read the result. A page is an .rst
file listed in a toctree of docs/index.rst; Markdown files under
docs/ are not built.
Every .. code-block:: yaml example must load through the strict loader,
which tests/test_doc_yaml_snippets.py checks. After changing the
arguments of a command-line program, regenerate the command-line reference,
and after changing a configuration field, the options reference, with the
package importable, and commit the page:
PYTHONPATH=$PWD/src python docs/scripts/generate_cli_reference.py
PYTHONPATH=$PWD/src python docs/scripts/generate_options_reference.py
With --check, either script fails when its page is out of date; the
pull-request checks run both that way.