CONTRIBUTE.md

How to contribute

All contributors are expected to comply with our Code of Conduct. This ensures a positive and inclusive environment for everyone involved.

User experiences, bugs, and feature requests

If you are using pyknos, we would be delighted to know how it worked for you. If it didn't work according to plan, please open up an issue and tell us more about your use case.

To report bugs and suggest features -- including better documentation -- please equally head over to issues on GitHub and tell us everything.

Contributing code

Contributions to the pyknos package are always welcome! The preferred way to do it is via pull requests onto our main repository. We mention all contributors in the releases.

To avoid duplicated work, we strongly suggest that you take a look at our current open issues and pull requests to see if someone else is already doing it. Also, in case you're planning to work on something that has not yet been proposed by others (e.g. adding a new feature, adding a new example), it is preferable to first open a new issue explaining what you intend to propose and then working on your pull request after getting some feedback from others.

Contribution workflow

The following steps describe all parts of the workflow for doing a contribution such as installing locally pyknos from source, creating a conda environment, setting up your git repository, etc. We've taken strong inspiration from the contribution guides for scikit-learn and mne:

Step 1: Create an account on GitHub if you do not already have one.

Step 2: Fork the project repository: click on the ‘Fork’ button near the top of the page. This will create a copy of the pyknos codebase under your GitHub user account. See more details on how to fork a repository here.

Step 3: Clone your fork of the pyknos repo from your GitHub account to your local disk:

git clone [email protected]:$USERNAME/sbi.git
cd sbi

Step 4: Install a recent version of Python (we currently recommend 3.10) for instance using miniforge. We strongly recommend you create a specific conda environment for doing development on pyknos as per:

conda create -n sbi_dev python=3.10
conda activate sbi_dev

Step 5: Install pyknos in editable mode with

pip install -e ".[dev]"

This installs the pyknos package into the current environment by creating a link to the source code directory (instead of copying the code to pip's site_packages directory, which is what normally happens). This means that any edits you make to the pyknos source code will be reflected the next time you open a Python interpreter and import pyknos (the -e flag of pip stands for an “editable” installation, and the dev flag installs development and testing dependencies). This requires at least Python 3.8.

Step 6: Add the upstream remote. This saves a reference to the main pyknos repository, which you can use to keep your repository synchronized with the latest changes:

git remote add upstream [email protected]:sbi-dev/pyknos.git

Check that the upstream and origin remote aliases are configured correctly by running git remote -v which should display:

origin  [email protected]:$USERNAME/pyknos.git (fetch)
origin  [email protected]:$USERNAME/pyknos.git (push)
upstream        [email protected]:sbi-dev/pyknos.git (fetch)
upstream        [email protected]:sbi-dev/pyknos.git (push)

Step 7: Install pre-commit to run code style checks before each commit:

pip install pre-commit
pre-commit install

You should now have a working installation of pyknos and a git repository properly configured for making contributions. The following steps describe the process of modifying code and submitting a pull request:

Step 8: Synchronize your main branch with the upstream/main branch. See more details on GitHub Docs:

git checkout main
git fetch upstream
git merge upstream/main

Step 9: Create a feature branch to hold your development changes:

git checkout -b my_feature

and start making changes. Always use a feature branch! It’s good practice to never work on the main branch, as this allows you to easily get back to a working state of the code if needed (e.g., if you’re working on multiple changes at once, or need to pull in recent changes from someone else to get your new feature to work properly). In most cases, you should make PRs into the upstream’s main branch.

Step 10: Develop your code on your feature branch on the computer, using Git to do the version control. When you’re done editing, add changed files using git add and then git commit to record your changes:

git add modified_files
git commit -m "description of your commit"

Then push the changes to your GitHub account with:

git push -u origin my_feature

The -u flag ensures that your local branch will be automatically linked with the remote branch, so you can later use git push and git pull without any extra arguments.

Step 11: Follow these instructions to create a pull request from your fork. This will send a notification to pyknos maintainers and trigger reviews and comments regarding your contribution.

It is often helpful to keep your local feature branch synchronized with the latest changes of the main pyknos repository:

git fetch upstream
git merge upstream/main

Style conventions and testing

All our docstrings and comments are written following the Google Style.

For code linting and formatting, we use ruff, which is installed alongside pyknos.

You can exclude slow tests and those which require a GPU with

pytest -m "not slow and not gpu"

Additionally, we recommend to run tests with

pytest -n auto -m "not slow and not gpu"

in parallel. GPU tests should probably not be run this way. If you see unexpected behavior (tests fail if they shouldn't), try to run them without -n auto and see if it persists. When writing new tests and debugging things, it may make sense to also run them without -n auto.

When you create a PR onto main, our Continuous Integration (CI) actions on GitHub will perform the following checks:

• ruff for linting and formatting (including black, isort, and flake8)
• pyright for static type checking.
• pytest for running a subset of fast tests from our test suite.

If any of these fail, try reproducing and solving the error locally:

• ruff: Make sure you have pre-commit installed locally with the same version as specified in the requirements. Execute it using pre-commit run --all-files. ruff tends to give informative error messages that help you fix the problem. Note that pre-commit only detects problems with ruff linting and formatting, but does not fix them. You can fix them either by running ruff check . --fix (linting), followed by ruff format .(formatting), or by hand.

• pyright: Run it locally using pyright sbi/ and ensure you are using the same pyright version as used in the CI (which is the case if you have installed it with pip install -e ".[dev]" but note that you have to rerun it once someone updates the version in the pyproject.toml).

  • Known issues and fixes:
    • If using **kwargs, you either have to specify all possible types of kwargs, e.g. **kwargs: Union[int, boolean] or use **kwargs: Any

• pytest: On GitHub Actions you can see which test failed. Reproduce it locally, e.g., using pytest -n auto tests/linearGaussian_snpe_test.py. Note that this will run for a few minutes and should result in passes and expected fails (xfailed).

• Commit and push again until CI tests pass. Don't hesitate to ask for help by commenting on the PR.

Contributing to the documentation

Most of the documentation for pyknos is written in markdown and the website is generated using mkdocs with mkdocstrings. To work on improvements of the documentation, you should first run the command on your terminal

mkdocs serve

and open a browser on the page proposed by mkdocs. Now, whenever you make changes to the markdown files of the documentation, you can see the results almost immediately in the browser.

Note that the tutorials and examples are initially written in jupyter notebooks and then converted to markdown programatically. To do so locally, you should run

jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorial/
jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/