Thank you for considering contributing to CausalNex! CausalNex would not be possible without the generous sharing from leading researchers in causal inference and we hope to maintain the spirit of open discourse by welcoming contributions in the form of pull requests (PRs), issues or code reviews. You can add to code, documentation, or simply send us spelling and grammar fixes or extra tests. Contribute anything that you think improves the community for us all!
The following sections describe our vision and contribution process.
Identifying causation from data remains a field of active research and CausalNex aims to become the leading library for causal reasoning and counterfactual analysis using Bayesian Networks.
The CausalNex team pledges to foster and maintain a welcoming and friendly community in all of our spaces. All members of our community are expected to follow our Code of Conduct and we will do our best to enforce those principles and build a happy environment where everyone is treated with respect and dignity.
We use GitHub Issues to keep track of known bugs. We keep a close eye on them and try to make it clear when we have an internal fix in progress. Before reporting a new issue, please do your best to ensure your problem hasn't already been reported. If so, it's often better to just leave a comment on an existing issue, rather than create a new one. Old issues also can often include helpful tips and solutions to common problems.
If you are looking for help with your code and our documentation hasn't helped you, please consider posting a question on Stack Overflow. If you tag it causalnex and python, more people will see it and may be able to help. We are unable to provide individual support via email. In the interest of community engagement we also believe that help is much more valuable if it's shared publicly, so that more people can benefit from it.
If you're over on Stack Overflow and want to boost your points, take a look at the causalnex tag and see if you can help others out by sharing your knowledge. It's another great way to contribute.
If you have already checked the existing issues in GitHub issues and are still convinced that you have found odd or erroneous behaviour then please file an issue. We have a template that helps you provide the necessary information we'll need in order to address your query.
If you have new ideas for CausalNex functionality then please open a GitHub issue with the label Type: Enhancement. You can submit an issue here which describes the feature you would like to see, why you need it, and how it should work.
If you're unsure where to begin contributing to CausalNex, please start by looking through the good first issues on GitHub.
We focus on two areas for contribution: core and contrib:
corerefers to the primary CausalNex librarycontribrefers to features that could be added tocorethat do not introduce too many dependencies e.g. adding a new type of causal network to network module.
Typically, we only accept small contributions for the core CausalNex library but accept new features as plugins or additions to the contrib module. We regularly review contrib and may migrate modules to core if they prove to be essential for the functioning of the framework or if we believe that they are used by most projects.
Working on your first pull request? You can learn how from these resources:
- Aim for cross-platform compatibility on Windows, macOS and Linux
- We use Anaconda as a preferred virtual environment
- We use SemVer for versioning
Our code is designed to be compatible with Python 3.5 onwards and our style guidelines are (in cascading order):
- PEP 8 conventions for all Python code
- Google docstrings for code comments
- PEP 484 type hints for all user-facing functions / class methods e.g.
def count_truthy(elements: List[Any]) -> int:
return sum(1 for elem in elements if element)
Note: We only accept contributions under the Apache 2.0 license and you should have permission to share the submitted code.
Please note that each code file should have a licence header, include the content of legal_header.txt.
There is an automated check to verify that it exists. The check will highlight any issues and suggest a solution.
We use a branching model that helps us keep track of branches in a logical, consistent way. All branches should have the hyphen-separated convention of: <type-of-change>/<short-description-of-change> e.g. contrib/structure
| Types of changes | Description |
|---|---|
contrib |
Changes under contrib/ and has no side-effects to other contrib/ modules |
docs |
Changes to the documentation under docs/source/ |
feature |
Non-breaking change which adds functionality |
fix |
Non-breaking change which fixes an issue |
tests |
Changes to project unit tests/ and / or integration features/ tests |
Small contributions are accepted for the core library:
- Fork the project by clicking Fork in the top-right corner of the CausalNex GitHub repository and then choosing the target account the repository will be forked to.
- Create a feature branch on your forked repository and push all your local changes to that feature branch.
- Before submitting a pull request (PR), please ensure that unit tests and linting are passing for your changes by running
make testandmake lintlocally, have a look at the section Running checks locally below. - Open a PR against the
quantumblacklabs:developbranch from your feature branch. - Update the PR according to the reviewer's comments.
- Your PR will be merged by the CausalNex team once all the comments are addressed.
Note: We will work with you to complete your contribution but we reserve the right to takeover abandoned PRs.
You can also add new work to contrib:
- Create an issue describing your contribution.
- Fork the project by clicking Fork in the top-right corner of the CausalNex GitHub repository and then choosing the target account the repository will be forked to.
- Work in
contriband create a feature branch on your forked repository and push all your local changes to that feature branch. - Before submitting a pull request, please ensure that unit tests and linting are passing for your changes by running
make testandmake lintlocally, have a look at the section Running checks locally below. - Include a
README.mdwith instructions on how to use your contribution. - Open a PR against the
quantumblacklabs:developbranch from your feature branch and reference your issue in the PR description (e.g.,Resolves #<issue-number>). - Update the PR according to the reviewer's comments.
- Your PR will be merged by the CausalNex team once all the comments are addressed.
Note: We will work with you to complete your contribution but we reserve the right to takeover abandoned PRs.
To run tests you need to install the test requirements. Also we use pre-commit hooks for the repository to run the checks automatically. It can all be installed using the following command:
make install-test-requirements
make install-pre-commitAll checks run by our CI / CD servers can be run locally on your computer.
make lintmake testNote: We place conftest.py files in some test directories to make fixtures reusable by any tests in that directory. If you need to see which test fixtures are available and where they come from, you can issue:
pytest --fixtures path/to/the/test/location.pyOur CI / CD also checks that causalnex installs cleanly on a fresh Python virtual environment, a task which depends on successfully building the docs:
make build-docsThis command will only work on Unix-like systems and requires pandoc to be installed.
The Docker images have all the necessary dependencies built in. To develop using the docker containers do the following
- Build the necessary container
export CONTAINER_TYPE='cpu' # or gpu
docker build -t quantumblacklabs/causalnex:devel-$CONTAINER_TYPE -f devel-$CONTAINER_TYPE.Dockerfile .- Run the container in interactive mode. For running on CPU, simply run the docker container:
docker run -it -w /causalnex_src -v $PWD:/causalnex_src quantumblacklabs/causalnex:devel-cpu bashFor the gpu type your host machine needs access to a GPU with the CUDA driver installed. The devel-gpu image will be able to access the gpu on the host
docker run --gpus all -it -w /causalnex_src -v $PWD:/causalnex_src quantumblacklabs/causalnex:devel-gpu bash- Run tests
make test- If all tests pass you can build the wheel
make package- Now you can install the pip package that has your changes in either the container or on your host machine. The name of installed package will be
causalnex
make installThe checks will automatically run on all the changed files on each commit.
Even more extensive set of checks (including the heavy set of pylint checks)
will run before the push.
The pre-commit/pre-push checks can be omitted by running with --no-verify flag, as per below:
git commit --no-verify <...>
git push --no-verify <...>(-n alias works for git commit, but not for git push)
All checks will run during CI build, so skipping checks on push will not allow you to merge your code with failing checks.
You can uninstall the pre-commit hooks by running:
make uninstall-pre-commitpre-commit will still be used by make lint, but will not install the git hooks.