lidarpy contributing

Development Workflow

Start from the roadmap, choose one bounded task, and validate only the surface you changed before running heavier groups. This keeps Windows and Linux development practical while still protecting the migrated scientific paths.

uv sync --group dev
$env:PYTHONPATH = "src"
$env:MPLBACKEND = "Agg"
.\.venv\Scripts\python -m pytest tests\synthetic tests\retrieval tests\scc -q

Expected result: focused tests pass from the checkout. If a change touches RAW conversion or preprocessing, run the relevant RAW-backed tests in a separate chunk after checking disk space.

Repository Conventions

Migration coordination belongs in ROADMAP.md and AGENTS.md.
User-facing documentation belongs under docs/.
Generated docs output belongs in site/ and should not be committed unless the workflow requires it.
Generated build artifacts belong in ignored folders such as artifacts/ or dist/.
Private SCC credentials, NAS paths and real heavy datasets must stay outside Git.
Do not reintroduce legacy modules that the roadmap has explicitly removed.

Testing Policy

Change type	Minimum useful tests	Why
Pure retrieval or synthetic logic	`pytest tests\synthetic tests\retrieval -q`	Validates numerical contracts without RAW fixture cost.
Preprocessing corrections	Focused tests under `tests\preprocessing`	Checks correction flags, signal variables and xarray contracts.
SCC local/client behavior	`pytest tests\scc -q`	Confirms package data and mocked HTTP client contracts without credentials.
Packaging rules	`pytest tests\packaging -q`	Ensures coordination files and RAW fixtures stay out of distributions.
Documentation links	`pytest tests\docs -q`	Prevents static pages from linking to missing local files.

Documentation Workflow

GitHub Pages is published by the docs workflow. Static pages live in docs/. The build script copies them into site/, regenerates figures, generates API HTML with pdoc, and uploads site/ as the Pages artifact.

$env:PYTHONPATH = "src"
$env:MPLBACKEND = "Agg"
.\.venv\Scripts\python scripts\build_docs.py

Expected result: site/index.html, site/assets/site.css and site/api/lidarpy.html exist. If a page is added, also update tests/docs/test_docs_links.py so CI checks its links and images.

Release Contributions

Release changes should be small and auditable: version metadata, changelog/roadmap notes, packaging checks and a tag. The publish workflow uses PyPI Trusted Publishing, so no PyPI token should be committed or stored in local config for this repository.

python -m build
python -m twine check dist/*
git tag v0.1.2
git push origin v0.1.2

Expected result: the GitHub Actions release workflow uploads checked artifacts to PyPI. If a release is bad, prefer publishing a fixed patch and pinning downstream systems to the last known good version.