We want to make contributing to BoTorch is as easy and transparent as possible.
To get the development installation with all the necessary dependencies for linting, testing, and building the documentation, run the following:
git clone https://github.com/pytorch/botorch.git
cd botorch
pip install -e .[dev]
BoTorch uses the black code formatter to
enforce a common code style across the code base. black is installed easily via
pip using pip install black
, and run locally by calling
black .
from the repository root. No additional configuration should be needed (see the black documentation for advanced usage).
BoTorch uses [ufmt]https://github.com/omnilib/ufmt library for consistent
sorting of imports across the codebase. Install via pip install ufmt
, and
auto-sort with
ufmt format .
from the repository root.
We feel strongly that having a consistent code style and imports is important, so CI will fail on your PR if it does not pass ufmt muster (note: under the hood ufmt also checks black code style).
BoTorch is fully typed using python 3.7+ type hints. We expect any contributions to also use proper type annotations. While we currently do not enforce full consistency of these in our continuous integration test, you should strive to type check your code locally. For this we recommend using pyre.
To run the unit tests, you can either use pytest
(if installed):
pytest -ra
or python's unittest
:
python -m unittest
To get coverage reports we recommend using the pytest-cov
plugin:
pytest -ra --cov=. --cov-report term-missing
BoTorch's website is also open source, and is part of this very repository (the code can be found in the website folder). It is built using Docusaurus, and consists of three main elements:
- The documentation in Docusaurus itself (if you know Markdown, you can already contribute!). This lives in the docs.
- The API reference, auto-generated from the docstrings using Sphinx, and embedded into the Docusaurus website. The sphinx .rst source files for this live in sphinx/source.
- The Jupyter notebook tutorials, parsed by
nbconvert
, and embedded into the Docusaurus website. These live in tutorials.
To build the documentation you will need Node >= 8.x and Yarn >= 1.5.
The following command will both build the docs and serve the site locally:
./scripts/build_docs.sh
We actively welcome your pull requests.
- Fork the repo and create your branch from
master
. - If you have added code that should be tested, add unit tests. In other words, add unit tests.
- If you have changed APIs, update the documentation. Make sure the documentation builds.
- Ensure the test suite passes.
- Make sure your code passes both
black
andflake8
formatting checks. - If you haven't already, complete the Contributor License Agreement ("CLA").
In order to accept your pull request, we need you to submit a CLA. You only need to do this once to work on any of Facebook's open source projects. You can complete your CLA here: https://code.facebook.com/cla
We use GitHub issues to track public bugs. Please ensure your description is clear and has sufficient instructions to be able to reproduce the issue.
Facebook has a bounty program for the safe disclosure of security bugs. In those cases, please go through the process outlined on that page and do not file a public issue.
By contributing to BoTorch, you agree that your contributions will be licensed under the LICENSE file in the root directory of this source tree.