Skip to content

Contributing to AeroViz

Thanks for your interest in improving AeroViz! Bug reports, feature requests, documentation fixes, and new instrument readers are all welcome.

  • Questions, bugs, ideas: open a GitHub Issue.
  • Code changes: fork, branch, and open a pull request (see below).

Development setup

Building from source — an editable pip install -e ., or any platform without a pre-built wheel — compiles a bundled Fortran extension (ISORROPIA II), so you need a Fortran compiler (gfortran) plus meson / ninja:

# Install a Fortran toolchain first:
#   macOS:          brew install gcc
#   Debian/Ubuntu:  sudo apt-get install gfortran
#   Windows:        use the MSYS2 / mingw-w64 toolchain

git clone https://github.com/Alex870521/AeroViz.git
cd AeroViz
pip install -e ".[test,dev]"

Running tests

pytest                      # full suite
pytest tests/test_readers   # just the instrument readers

The reader tests run against small fixtures in tests/fixtures/raw_data/. Keep the requested date ranges tight — RawDataReader reindexes to the requested window, so a wide range over a small fixture inflates the cached pickle.

Code style

Match the style of the surrounding code. The dev extra installs black, isort, flake8, and mypy if you'd like to format and lint locally; none are enforced in CI, so use your judgement and keep diffs focused.

Commit messages

Commit messages follow Conventional Commits: type(scope): subject, e.g. fix(reader): handle empty AE33 file. Common types are feat, fix, docs, refactor, test, ci, chore. The commit history drives the changelog and the next version number, so a clear subject matters.

Pull requests

  1. Branch off main.
  2. Make focused changes with conventional-commit messages.
  3. Add or update tests, and run pytest.
  4. Update the docs (README.md, docs/, or the relevant docstring) if you changed behaviour.
  5. Open the PR with a short description of the what and why.

Adding a new instrument

A reader is a Reader subclass in AeroViz/rawDataReader/script/<NAME>.py (auto-imported) plus a meta entry in AeroViz/rawDataReader/config/supported_instruments.py, a fixture-backed test in tests/test_readers/, and a docs page. The step-by-step contract — hooks, status register, severities, what the tests pin — is in Contributing a Reader (docs/guide/contributing-reader.md).

Releases (maintainers)

Releases are cut with Commitizen, which derives the next version from the commit history, updates docs/CHANGELOG.md, and tags vX.Y.Z:

  • Run the Bump version workflow from the Actions tab, or cz bump locally followed by git push --follow-tags.
  • Pushing the vX.Y.Z tag triggers the Release workflow, which builds the wheels and publishes to PyPI via OIDC.