Oleg Sheynin
55 lines
1.7 KiB
Markdown
55 lines
1.7 KiB
Markdown
# Contributing
|
|
|
|
## Setup
|
|
|
|
Use the shared Python 3.12 virtual environment:
|
|
|
|
```bash
|
|
source ~/.pyenv/python3.12-venv/bin/activate
|
|
python -m pip install -r requirements.txt
|
|
```
|
|
|
|
If you install another package for repository work, add its direct dependency
|
|
to `requirements.txt`.
|
|
|
|
## Repository layout
|
|
|
|
- Put notebooks in `notebooks/`.
|
|
- Put reusable Python and Bash utilities in `scripts/`.
|
|
- Put local input files in `data/`.
|
|
- Put generated artifacts in `results/`.
|
|
|
|
The contents of `data/` and `results/` are ignored. Do not force-add test
|
|
databases, raw test results, generated exports, or notebook outputs.
|
|
|
|
`__SAV__/` is unrelated legacy material and is outside the active project.
|
|
|
|
## Working with notebooks
|
|
|
|
Notebooks must execute from top to bottom in a fresh kernel. Use relative paths,
|
|
document data assumptions, and move reusable logic into tested scripts.
|
|
|
|
Before handing off a change:
|
|
|
|
```bash
|
|
python -m pytest
|
|
python -m pytest --nbmake notebooks
|
|
jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace path/to/notebook.ipynb
|
|
```
|
|
|
|
Run only the checks relevant to the files present in the repository, and report
|
|
anything that could not be run.
|
|
|
|
## Review requirement
|
|
|
|
Python scripts, Bash scripts, and notebook code-cell changes require review and
|
|
approval by a separate background agent. Address material findings and rerun
|
|
affected checks before completion. If a reviewer is unavailable, the change may
|
|
be handed off only with the status `review pending`.
|
|
|
|
Documentation, dependency declarations, and ignore rules do not require this
|
|
background review when no Python, Bash, or notebook code cells changed.
|
|
|
|
The `master` branch is not protected. That does not remove the review
|
|
requirement or authorize an agent to commit or push without an explicit request.
|