Skip to content

Contributing

Source: CONTRIBUTING.md

Contributions are welcome — bug reports and pull requests alike. mizu is pre-release and the API can change at any time, so open an issue to discuss larger changes before doing the work.

Reporting bugs

Open a GitHub issue with a minimal reproducer, your platform, and your R version. For a pool that hangs, include the output of mizu_pool_dump() — it is the first diagnostic tool.

Pull requests

Set up and run the checks before submitting:

R CMD INSTALL .
Rscript -e 'devtools::test()'

The cross-process tests spawn fresh Rscript children that load mizu from the installed library, so install before testing — a stale installed copy runs different code than the test process. Run Rscript -e 'devtools::check()' for the full check.

Conventions:

  • Commit messages are a single-line subject, no body.
  • New behavior needs a test. Tests for R/{name}.R live in tests/testthat/test-{name}.R, next to similar existing tests.
  • Never edit src/vendor/libmizu/ by hand. Changes go upstream to libmizu and land here via tools/vendor-libmizu.sh.
  • Edit README.Rmd, never README.md — regenerate with devtools::build_readme().
  • Vignette sources are dev/vignettes/_{name}.qmd — regenerate with Rscript dev/vignettes/precompile.R.
  • Cross-language tests skip unless a python3 with pymizu and NumPy is installed.

Repository layout

  • R/: the package source — the channel, pool, and map surfaces, spawning, and the condition hierarchy.
  • src/: the C layer — the .Call veneer, the SEXP staging hooks, the compact codec, and the ALTREP view layer.
  • src/vendor/libmizu/: the vendored libmizu core, generated by tools/vendor-libmizu.sh. Do not edit these files by hand.
  • tests/testthat/: the testthat suite. helper.R holds the deterministic in-process harnesses (channel_pair(), pool_pair()).
  • dev/vignettes/: the pre-computed vignette sources; rendered output lands in vignettes/.

Code of conduct

This project is released with a Contributor Code of Conduct. By participating, you agree to abide by its terms.

License

By contributing, you agree that your contributions are licensed under the project’s MIT license.