Guide/Introduction to open-source contribution and project standardization
Overview
The Miniscope project is built and maintained as a collection of open-source repositories spanning hardware designs, firmware, software tools, documentation, and analysis pipelines. All development happens in the open on GitHub, and contributions from the community -- whether bug reports, documentation improvements, code patches, or new tool integrations -- are a core part of how the project grows.
This guide introduces how the Miniscope project is organized, how we standardize development practices across repositories, and how you can contribute.
Project Organization
Miniscope development is distributed across three GitHub organizations:
- github.com/miniscope -- Core Miniscope hardware, firmware, acquisition software, and analysis tools (Minian, Minisim, CaLab, and others).
- github.com/aharoni-lab -- Lab-developed tools and infrastructure that support the Miniscope ecosystem.
- github.com/labki-org -- The Labki wiki platform and its extensions (SemanticSchemas, SchemaSync, MWAssistant) that power miniscope.org.
Each repository follows a common set of practices described below. If you are looking for a specific tool or resource, start at the organization pages above and browse the available repositories.
Standardization Practices
To maintain quality and consistency across the ecosystem, we are working towards all Miniscope repositories following standardized practices for continuous integration, testing, and release management:
- Version control and branching: All repositories use Git with a main branch as the stable default. Feature work happens on branches and is merged via pull requests with review.
- Continuous integration (CI): Automated testing runs on every pull request via GitHub Actions. This includes software unit tests, firmware build verification, hardware-in-the-loop (HIL) validation for physical devices, and design rule checks for PCB layouts (KiCad KLC validation).
- Releases and versioning: Stable releases are tagged and published through GitHub Releases with changelogs. Software packages are published to PyPI where applicable. Firmware builds are generated automatically by CI/CD pipelines.
- Documentation: Each tool is expected to have user-facing documentation, either on miniscope.org, ReadTheDocs, or within the repository itself.
- Licensing: All project outputs are released under open-source licenses (typically GPL-3.0 for software and open hardware licenses for designs).
These practices are formalized in the project's CI and Tool Maintenance Plan and QA/QC Plan, developed under NIH U24 NS144101.
How to Contribute
There are many ways to contribute to the Miniscope project, and you do not need to be an experienced developer to help.
Report Issues and Suggest Improvements
The most common and valuable contribution is reporting problems or suggesting features. Every repository has an Issues tab on GitHub for this purpose.
Guide/How and why to submit an issue
That guide walks through when and how to submit an issue, what information to include, and how the team triages and responds.
Improve Documentation
If you find a guide that is unclear, incomplete, or out of date, you can suggest edits. On miniscope.org, use the Discussion Forum to flag documentation issues. For repository-level docs (READMEs, ReadTheDocs pages), open an issue or submit a pull request directly.
Contribute Code or Designs
For code or hardware design contributions we suggest starting with submitting an issue on that repository. This gives us a space to discuss and plan before work is done.
- Find the relevant repository on one of the GitHub organizations linked above.
- Check existing issues to see if the problem or feature is already tracked. Post your ideas/issue/feature here.
- Fork the repository and create a branch for your changes.
- Follow the repository's contribution guidelines if a CONTRIBUTING file is present.
- Open a pull request with a clear description of what you changed and why.
All pull requests go through CI checks and code review before merging.
If you have developed workflows, surgical protocols, analysis scripts, or training materials that could benefit the community, the Discussion Forums here are the place to share them. High-quality community contributions may be promoted to formal guides on the platform.
Getting Help
If you are unsure where to contribute or have questions about the development process, the best starting points are:
- The Discussion Forum
- The Issues tab on the relevant GitHub repository
- The project mailing list (subscribe via [1])