Contributing Guide

Contributing Guide#

Thank you for contributing to brainmass!

Ways to Contribute#

  • Code: New models, features, bug fixes

  • Documentation: Tutorials, API docs, examples

  • Examples: Jupyter notebooks demonstrating use cases

  • Bug reports: Issue reports with reproducible examples

  • Feature requests: Proposals for new functionality

Development Setup#

  1. Fork the repository on GitHub

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/brainmass.git
cd brainmass

  3. Install in development mode:

    pip install -e .[dev,doc]

  4. Create a branch:

    git checkout -b feature/my-feature

Code Guidelines#

Style:

  • Follow PEP 8

  • Use type hints

  • Write descriptive variable names

  • Keep functions focused and small

Documentation:

  • Add docstrings to all public functions/classes

  • Use Google-style docstrings

  • Include examples in docstrings

  • Update relevant tutorial/API docs

Testing:

  • Write tests for new features

  • Ensure existing tests pass

  • Aim for >80% code coverage

Pull Request Process#

  1. Before submitting:

    • Run tests: pytest tests/

    • Check code style: ruff check brainmass/

    • Build docs: make -C docs html

    • Update CHANGELOG

  2. PR description:

    • Describe what changed and why

    • Reference related issues

    • Include examples if applicable

  3. Review process:

    • Maintainers will review within a week

    • Address feedback

    • Once approved, PR will be merged

Testing#

Run all tests:

pytest tests/

Run specific test:

pytest tests/test_models.py::test_hopf_oscillator

Documentation#

Build documentation locally:

cd docs
make html
# Open _build/html/index.html

Add new documentation to appropriate section (API, tutorials, examples).

Commit Messages#

Use clear, descriptive commit messages:

  • Start with verb (Add, Fix, Update, etc.)

  • Keep first line under 72 characters

  • Add details in body if needed

Good examples:

Add QIF model implementation

Fix coupling bug in DiffusiveCoupling

Update installation docs for Windows

Reporting Issues#

Good bug reports include:

  1. Minimal reproducible example

  2. Expected vs actual behavior

  3. Environment info (OS, Python version, brainmass version)

  4. Error messages/tracebacks

Feature Requests#

Feature requests should:

  1. Describe the use case

  2. Explain why it’s valuable

  3. Suggest implementation approach (optional)

  4. Consider backward compatibility

Code Review#

When reviewing:

  • Be constructive and respectful

  • Focus on code, not person

  • Suggest improvements, don’t demand

  • Approve when ready

Release Process#

(For maintainers)

  1. Update version in pyproject.toml

  2. Update CHANGELOG.md

  3. Create release tag

  4. Build and publish to PyPI

Getting Help#

  • Questions: GitHub Discussions

  • Stuck: Ask in your PR

  • Other: Email maintainers

Thank You!#

Every contribution helps make brainmass better for everyone.