Contributing#
OrbitalPV welcomes reproducible improvements to models, connectors, analytics, tests, examples, and documentation.
Development setup#
git clone https://github.com/julianascencio/orbital-pv.git
cd orbital-pv
uv sync --all-packages --group dev --group lab --group docs
Before opening a pull request#
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest
make docs
AI-assisted contribution policy#
OrbitalPV is intentionally AI-assisted. A substantial share of repository content may be generated or drafted with AI, including code, documentation, tests, examples, and research synthesis.
AI assistance does not replace scientific provenance. Contributors should:
select and cite the specific literature, datasets, standards, or technical reports that motivate a method or parameterization;
distinguish literature-backed values from engineering assumptions, placeholders, or illustrative defaults;
review AI-generated implementations for physical validity, numerical correctness, units, edge cases, and reproducibility;
add tests and validation evidence appropriate to the claimed fidelity;
avoid presenting AI-generated text or code as independent scientific validation;
update the literature library when new sources materially influence the repository.
The intended workflow is developer-selected evidence -> AI-assisted implementation -> human review, testing, and progressive validation. Some parts of the repository remain early-stage and may contain AI-generated errors or imperfect interpretations, so deeper validation should grow alongside the project.
Scientific contributions#
Model or analysis changes should state:
the physical or statistical assumptions;
reference frame and time convention where relevant;
units;
source data and provenance;
validation evidence;
known limitations;
deterministic seeds for stochastic experiments.
Documentation#
User-facing functionality should include both conceptual documentation and API docstrings. Add an executable gallery example when a visual or end-to-end workflow is the clearest way to teach the feature.
Public repository hygiene#
Keep documentation and examples focused on OrbitalPV and public technical sources. Do not include private employer, client, credential, or proprietary system information.