Contributing to BayesFlow

Contributing to BayesFlow#

Workflow#

If you start working on a new feature or a bug fix, please create an issue on GitHub describing the issue and assign yourself.

Make sure that you are working in the Development branch, which contains the latest updates. Create an own branch or use a fork, where you can implement your changes. To merge your work, please follow these steps:

  1. Create a pull request to the Development branch with a short summary of the code changes;

  2. Check that code changes are covered by tests, and all tests pass;

  3. Check that the documentation is up-to-date;

  4. Request a code review from the main developers.

Environment#

If you want to contribute to the development of BayesFlow, you need to install developer requirements via:

pip install -r requirements_dev.txt

Tox#

Second, this installs the virtual testing tool tox https://tox.readthedocs.io/en/latest/, which we use for all tests, formatting and quality checks. Its configuration is specified in tox.ini. To run it locally, simply execute:

tox [-e flake8]

with an optional -e flag specifying the environments to run. See tox.ini for more details.

Pre-commit hooks#

Pre-commit hooks are used to examine the fidelity of the code that’s about to be committed. For this, you need to install a pre-commit tool (e.g., https://pre-commit.com/).

To add those hooks to the .git folder of your local clone such that they are automatically executed on every commit, run::

pre-commit install

When adding new hooks, consider manually running pre-commit run --all-files once, as usually only the diff is checked. The configuration is specified in .pre-commit-config.yaml.

GitHub Actions#

We use GitHub Actions for automatic continuous integration testing (features/actions). All tests are run on pull requests and required to pass. The configuration is specified in .github/workflows/tests.yml.

Unit tests#

Unit tests are located in the tests folder. All files starting with test_ contain tests and are automatically run via GitHub Actions. We use pytest (https://docs.pytest.org/en/latest/) for our testing environment.

You can run the all tests locally via:

pytest -e

Or a specific test via:

pytest -e test_[mytest]

Tutorial Notebooks#

New tutorial notebooks are always welcome! You can add your tutorial notebook file to examples/ and add a reference to the list of notebooks in docsrc/source/examples.rst. Re-build the documentation (see below) and your notebook will be included.

Documentation#

The documentation uses sphinx and relies on numpy style docstrings in classes and functions. The overall structure of the documentation is manually designed. This also applies to the API documentation. This has two implications for you:

  1. If you add to existing submodules, the documentation will update automatically (given that you use proper numpy docstrings).

  2. If you add a new submodule or subpackage, you need to add a file to docsrc/source/api and a reference to the new module to the appropriate section of docsrc/source/api/bayesflow.rst.

You can re-build the documentation with

cd docsrc/
make clean && make github

The entry point of the rendered documentation will be at docs/index.html.

Contents