Contributors to BrainGlobe are absolutely encouraged, whether to fix a bug, develop a new feature, or add a new atlas.
There are many BrainGlobe repositories, so it may not be obvious where a new contribution should go. If you’re unsure about any part of the contributing process, please get in touch. The best place for questions about contributing is probably the BrainGlobe Zulip chat.
If for any reason, you’d rather not reach out in public, feel free to send a direct message on Zulip to Adam Tyson, one of the core developers.
Some of our tools have additional information about how data files are organised, where user caches are placed, and similar. You can view these repositories and the relevant information by heading to the specific repository developer docs page.
To contribute a new atlas#
To add a new BrainGlobe atlas, please see the guide here.
Creating a development environment#
It is recommended to use
conda to install a development environment for
BrainGlobe projects. Once you have
conda installed, the following commands
will create and activate a
conda environment with the requirements needed
for a development environment:
conda create -n brainglobe-dev -c conda-forge python=3.11 napari conda activate brainglobe-dev
This installs packages that often can’t be installed via
pyqt. The specific version of
Python is chosen to allow
TensorFlow to be
installed on macOS arm64 machines.
To install a specific BrainGlobe project for development, clone the GitHub repository, and then run
pip install -e .[dev]
Or if using
pip install -e '.[dev]'
from inside the repository. This will install the package, its dependencies, and its development dependencies.
In all cases, please submit code to the main repository via a pull request. The developers recommend, and adhere, to the following conventions:
Please submit draft pull requests as early as possible (you can still push to the branch once submitted) to allow for discussion.
One approval of a PR (by a repo owner) is enough for it to be merged.
Unless someone approves the PR with optional comments, the PR is immediately merged by the approving reviewer.
Please merge via “Squash and Merge” on GitHub to maintain a clean commit history.
Ask for a review from someone specific if you think they would be a particularly suited reviewer (possibly noting why they are suited on the PR description)
To improve the documentation#
Documentation for BrainGlobe is very important because it is aimed at researchers who may not have much computational experience. In particular:
Installation, although simple via PyPI, assumes a lot (e.g. functional Python installation, CUDA installation etc.).
There are a lot of parameters that can be changed, and their impact on the final results is not always obvious.
It is not immediately obvious how to use the results of the pipeline to answer the particular biological question.
For these reasons (and others) every part of all software must be documented as well as possible, and all new features must be fully documented.
Editing the documentation#
The documentation is hosted using GitHub Pages, and the source can be found at
GitHub. Most content is found under
docs/source, where the
structure mostly mirrors the rendered website. To edit a page, please:
Fork the repository
Make edits to the relevant pages
Create a pull request outlining the changes made
If you aren’t sure where the changes should be made, please get in touch.