Contributing

Pull requests

Work on a branch and open a pull request into main. Before opening it:

  1. Merge the latest main into your branch and resolve conflicts.

  2. Run the tests: OMP_NUM_THREADS=1 pytest (add -rP to show print output).

  3. Add tests for new features, and comment the code.

  4. Fill out the pull request template.

A reviewer approves when the tests pass on GitHub Actions and locally, and the changes are clear and commented. When asking for changes, describe precisely what needs to be fixed.

Tests

Tests live in tests/: files named test_*.py with functions named test_*, run by pytest. They must work on any number of MPI ranks: every collective is called by every rank, and assertions are reduced over the entities each rank owns.

Documentation

The website is built with Sphinx from the Markdown (MyST) pages in docs/src/ and published to https://lsdolab.github.io/DRAGonFLy by the docs GitHub Actions workflow on every push to main.

  • Add a page as a .md file in docs/src/ and list it in the toctree of docs/src/welcome.md.

  • Equations use $...$ and $$...$$; references go in docs/src/references.bib and are cited with {cite:p}`key` .

  • The API reference is generated from the docstrings in dragonfly_sim.

  • Build locally with pip install -r requirements.txt, then make html in docs/, and open docs/_build/html/index.html.

Releases

Update __version__ in dragonfly_sim/__init__.py and add an entry to Release notes.