Contributing#
The code for MUSICA is hosted on GitHub. For any proposed changes (bug fixes, new features, documentation updates, etc.), please start by opening an issue describing your request or planned contribution.
Creating a development environment#
To contribute to MUSICA and test changes locally, we recommend making a conda environment:
$ git clone https://github.com/NCAR/musica.git
$ cd musica
$ conda create --name musica python=<minimum-3.9> --yes
$ conda activate musica
After the GitHub repository is cloned and the virtual environment made, the MUSICA project can be built as follows:
$ mkdir build && cd build
$ ccmake ..
$ make
and pip can be used for an editable installation:
$ pip install -e .
For detailed developer options and dependency management, see our Software Development Plan.
Types of contributions#
We appreciate all types of contributions:
Code Contributions#
Bug fixes
New features
Performance improvements
Test coverage improvements
Documentation#
README improvements
Code documentation
Tutorial and example updates
Wiki contributions
Testing and Validation#
Bug reports with reproducible examples
Testing on different platforms
Validation against known results
Scientific Contributions#
New chemical mechanisms
Algorithm improvements
Performance optimizations
Contribution process#
Fork the repository and create a feature branch
Make your changes following our coding standards
Add tests for new functionality
Update documentation as needed
Submit a pull request with a clear description
Development guidelines#
This section outlines best practices and requirements for contributing code, managing dependencies, and ensuring compatibility across platforms.
Code standards#
Follow existing code style and conventions. We primarily follow the Google C++ Style Guide and PEP 8 for Python.
Include appropriate tests for new functionality
Document new features and APIs
Dependency management#
We use CMake for C++ dependencies and pip for Python dependencies. See our README for information about specifying dependency versions during development.
GPU support#
If contributing GPU-related code, please test on appropriate hardware and follow our GPU build guidelines.
Documentation#
All of our docs are stored in the docs
directory and built using Sphinx.
There are several Python dependencies that are necessary to build the documentation locally. These dependencies can be installed by
running the following from your cloned music-box
directory:
$ cd docs
$ pip install -r requirements.txt
For contributors wanting to visualize changes to the C++ API Reference, a separate xml folder must be generated in the /build
folder with the following command run from the docs
directory:
$ doxygen Doxyfile.in
To build the documentation locally after edits:
On macOS/Linux:
make html
On Windows (cmd or PowerShell):
.\make.bat html
Recognition policy#
We believe in recognizing all contributors appropriately:
Core Development Team#
Contributors who make substantial, ongoing contributions to the codebase, architecture, or project direction will be listed as authors in:
pyproject.toml (for Python package metadata)
.zenodo.json (as “creators” for software citations)
AUTHORS.md (as core developers)
Additional Contributors#
Contributors who make valuable but smaller contributions will be acknowledged in:
.zenodo.json (as “contributors” with appropriate type)
AUTHORS.md (in the Additional Contributors section)
GitHub’s contributor list (automatic)
Questions?#
Check our documentation
Read our Software Development Plan
Contact the maintainers at musica-support@ucar.edu
Thank you for your interest in contributing to MUSICA!