Contributing

Contributing#

Contributions of all kinds are welcome — bug reports, fixes, new channels, documentation, and examples. braincell is developed on GitHub at chaobrain/braincell.

Development setup#

Clone the repository and install in editable mode with the testing extras, then install the pre-commit hooks:

git clone https://github.com/chaobrain/braincell.git
cd braincell
pip install -e ".[testing]"
pre-commit install

The workflow#

  1. Open an issue (or find one) describing the bug or feature.

  2. Create a branch for your work.

  3. Write a test first. The project convention is: reproduce a bug with a failing test, then fix until it passes. See Testing.

  4. Implement the change, keeping code simple and intuitive.

  5. Run the checks locally:

    pytest braincell/
pre-commit run --all

  6. Open a pull request referencing the issue.

Coding conventions#

These conventions come from the project’s developer guide and keep the codebase coherent:

  • Units are mandatory. Every physical quantity must carry an explicit brainunit unit; bare numbers are rejected. See Units.

  • One canonical namespace per API. Public symbols are re-exported through the top-level braincell namespace; internal packages are underscore-prefixed (_cv, _compute, …). See Project Layout.

  • Ask when requirements are ambiguous rather than guessing.

  • NumPy-style docstrings for every public class, method, and function, with a runnable, doctestable Examples section where it helps.

  • Absolute imports for internal modules (from braincell.morph import Morphology).

Documentation#

Documentation lives in docs/ and is built with Sphinx (sphinx_book_theme, MyST, and myst-nb for notebooks). To build locally:

cd docs
make html        # output in docs/_build/html

Narrative pages are Markdown (MyST) or reStructuredText; tutorials and examples are Jupyter notebooks. The API reference is generated from docstrings via autosummary, so improving a docstring improves the reference automatically.

See also#