Contributing to BrainPy#
Everyone can contribute to BrainPy, and we value everyone’s contributions. There are several ways to contribute, including:
Improving or expanding BrainPy’s documentation
Contributing to BrainPy’s code-base
Contributing to BrainPy’s examples
Contributing in any of the above ways to the broader ecosystem of libraries built on BrainPy.
Ways to contribute#
For other proposals, we ask that you first open a GitHub Issue to seek feedback on your planned contribution.
Contributing code using pull requests#
We do all of our development using git, so basic knowledge is assumed.
Follow these steps to contribute code:
Fork the BrainPy repository by clicking the Fork button on the repository page. This creates a copy of the BrainPy repository in your own account.
Install Python >= 3.9 locally in order to run tests.
pipinstalling your fork from source. This allows you to modify the code and immediately test it out:
git clone https://github.com/YOUR_USERNAME/BrainPy cd BrainPy pip install -r requirements-dev.txt # Installs all testing requirements. pip install -e . # Installs BrainPy from the current directory in editable mode.
Add the BrainPy repo as an upstream remote, so you can use it to sync your changes.
git remote add upstream https://www.github.com/brainpy/BrainPy
Create a branch where you will develop from:
git checkout -b name-of-change
Make sure your code passes BrainPy’s lint and type checks, by running the following from the top of the repository:
pip install pre-commit pre-commit run --all
See Linting and Type-checking for more details.
Make sure the tests pass by running the following command from the top of the repository:
pytest -n auto tests/
BrainPy’s test suite is quite large, so if you know the specific test file that covers your changes, you can limit the tests to that; for example:
pytest -n auto brainpy/_src/tests/test_mixin.py
You can narrow the tests further by using the
pytest -kflag to match particular test names:
pytest -n auto brainpy/_src/tests/test_mixin.py -k testLogSumExp
BrainPy also offers more fine-grained control over which particular tests are run; see running-tests for more information.
Once you are satisfied with your change, create a commit as follows ( how to write a commit message):
git add file1.py file2.py ... git commit -m "Your commit message"
Then sync your code with the main repo:
git fetch upstream git rebase upstream/main
Finally, push your commit on your development branch and create a remote branch in your fork that you can use to create a pull request from:
git push --set-upstream origin name-of-change
Please ensure your contribution is a single commit (see Single-change commits and pull requests)
Create a pull request from the BrainPy repository and send it for review. Check the BrainPy pull request checklist for considerations when preparing your PR, and consult GitHub Help if you need more information on using pull requests.
BrainPy pull request checklist#
As you prepare a BrainPy pull request, here are a few things to keep in mind:
Single-change commits and pull requests#
A git commit ought to be a self-contained, single change with a descriptive message. This helps with review and with identifying or reverting changes if issues are uncovered later on.
Pull requests typically comprise a single git commit. (In some cases, for
instance for large refactors or internal rewrites, they may contain several.)
In preparing a pull request for review, you may need to squash together
multiple commits. We ask that you do this prior to sending the PR for review if
git rebase -i command might be useful to this end.
Linting and Type-checking#
pip install pre-commit pre-commit run --all
If your pull request touches documentation notebooks, this will also run some checks on those (See update-notebooks for more details).
Full GitHub test suite#
Your PR will automatically be run through a full test suite on GitHub CI, which covers a range of Python versions, dependency versions, and configuration options. It’s normal for these tests to turn up failures that you didn’t catch locally; to fix the issues you can push new commits to your branch.
Restricted test suite#
Once your PR has been reviewed, a BrainPy maintainer will mark it as
Pull Ready. This
will trigger a larger set of tests, including tests on GPU and TPU backends that are
not available via standard GitHub CI. Detailed results of these tests are not publicly
viewable, but the BrainPy maintainer assigned to your PR will communicate with you regarding
any failures these might uncover; it’s not uncommon, for example, that numerical tests
need different tolerances on TPU than on CPU.