Skip to content

Contributing

Contributing to openauc-io

Thanks for your interest in openauc-io. This project is in its pre-alpha foundation stage; APIs and structure will change. Contributions, issues and design discussion are welcome.

Development setup

Requires uv and a supported Python (3.11–3.13).

git clone https://github.com/ronfinn/openauc-io
cd openauc-io
uv sync
uv run pre-commit install   # optional: run checks on each commit

Running checks

All checks are run in CI across Python 3.11, 3.12 and 3.13. Run them locally before opening a pull request:

uv run ruff check .      # lint
uv run ruff format .     # format (use --check to verify only)
uv run mypy              # static type checking (strict)
uv run pytest            # tests with coverage

Project conventions

  • src layout, packaged with hatchling, managed with uv.
  • Typed: the package ships py.typed; mypy runs in strict mode.
  • Public API: exported through openauc/api.py. Internal module paths are not part of the public contract — export new public symbols through the facade.
  • Style: enforced by ruff (lint + format). Do not hand-format around it.

Architecture Decision Records

Non-trivial design choices are recorded as ADRs in docs/decisions/. Propose a new ADR (status Proposed) before implementing a decision it would govern. The current ADRs are ADR-0001 (package architecture), ADR-0002 (canonical data model), ADR-0003 (AUCX container) and ADR-0004 (parser plugin registry).

The development-log/ directory records session-level context and the phased roadmap.

Scientific and licensing boundaries

These are binding on all contributions:

  • Independent implementation. Do not copy source code or reproduce proprietary interfaces from SEDFIT, SEDPHAT, UltraScan, GUSSI, AUCAgent or other closed or incompatibly licensed software.
  • No fabricated format rules. Do not invent undocumented behaviour for existing third-party formats. Public specifications and literature may be cited as references, with provenance kept clear.
  • No silent inference. Missing required scientific metadata must fail validation loudly; radial data must not be silently interpolated or resampled.
  • Honest claims. Do not claim support for untested formats or scientific validation that has not been performed.
  • No bundled third-party binaries.
  • Test data must be synthetic or provably redistributable.

By contributing you agree that your contributions are licensed under the project's Apache License 2.0.

Development logs

Every substantial capability lands with a numbered log in development-log/ recording accepted decisions, rejected alternatives, limitations and next steps. If you add a capability, add a log.

Quality gates

Run before opening a pull request, from the repository root:

uv sync --all-groups
uv run ruff format .
uv run ruff check .
uv run mypy
uv run pytest
uv run mkdocs build --strict

Before a release checkpoint, also:

uv run pytest --cov=openauc --cov-report=term-missing
uv build
git diff --check

Typing is strict. Do not weaken typing, validation or tests to make a check pass — narrow types with assertions instead.

Documentation

The site is MkDocs Material. Preview it locally:

uv run mkdocs serve

Then open http://127.0.0.1:8000/.

Documentation is part of the deliverable, not an afterthought. A capability without a how-to page and a docstring is not finished.

Documentation rules

  • Never claim vendor-format compatibility, scientific analysis, physical simulation, unit conversion, PyPI availability or scientific validation.
  • Keep representation, structural validation, analysis readiness and scientific suitability distinct, using the vocabulary in the ADRs.
  • Give concrete examples, never bare path/to/file placeholders.
  • State the directory a command runs from.
  • Do not document an API or option without testing it.

Test data

Synthetic only. No real or confidential instrument data is ever committed. A release-readiness test enforces this.

For substantial fixtures use the synthetic generator rather than hand-writing CSV.

Extending parsers

The registry is decorator-based; see Parser detection and ADR-0004. A parser must never guess: ambiguity raises rather than picking.