Guide/How and why to submit an issue

Review interval	12 months
Status	No reviews recorded yet — needs first review

Submitting GitHub Issues

Miniscope tools are built by and for the community. When something doesn't work, feels confusing, or could be better, we want to hear about it. This guide walks you through the how and why of submitting issues on GitHub, and hopefully convinces you that doing so is a valuable contribution you can make to a project.

Why bother?

Let's start with the most important part: why should you take the time to submit an issue?

You're not complaining, you're contributing

There's a common feeling that submitting a bug report or feature request is somehow being a nuisance. It's the opposite. When you report a problem, you're doing the project a favor. Most of the time, the developers don't know about the issue. We can't fix what we don't know is broken, and we can't improve what we don't know is confusing. Every issue you submit is a data point that helps us understand how our tools are actually being used in the real world, which is often quite different from how we imagined they'd be used when we built them.

Your "obvious" issue probably isn't obvious to us

You might think, "surely they already know about this." Maybe. But probably not. And even if we do, having a concrete report from a real user gives us the context and motivation to actually prioritize a fix. It also lets us know how many people are affected.

It doesn't have to be a bug

Despite the name "Issues," GitHub Issues are used for much more than reporting bugs. They're a general-purpose way to communicate with the development team. You can use them for bug reports and things that are broken, feature requests and ideas for improvement, general feedback about your experience, and questions about how something works or why it works a certain way.

Think of it less like filing a complaint and more like starting a conversation.

Wait, what even is a "GitHub Issue"?

The term "GitHub Issue" can sound intimidating, or worse, like you're accusing someone of doing something wrong. It's a bit of an unfortunate name. In practice, a GitHub Issue is just a structured way to start a conversation with the people who build and maintain a project. It's like a forum post, but attached directly to the codebase so that developers can easily cross-reference it with the actual code, link it to fixes, and track its status over time. The word "issue" here doesn't mean "problem" in the negative sense. It means "topic" or "item to discuss." GitHub chose the name, and we're stuck with it, but don't let it make you feel like you need to have found a catastrophic bug before you're "allowed" to submit one. You don't. Feature requests, questions, feedback, and even just sharing your experience are all perfectly valid uses of Issues.

Our GitHub organizations

The Miniscope Project spans several GitHub organizations. Depending on what tool or component you're working with, you'll want to submit your issue to the right place:

miniscope — Community-facing tools and applications. This is where most users will submit issues. Repos include CaLab (calcium imaging analysis), noob, mio (miniscope I/O SDK), and more.
aharoni-lab — Lab-managed repositories, including hardware designs like Miniscope V4, firmware, and analysis tools.
labki-org — The wiki platform itself (Labki). If you're having issues with the wiki infrastructure, extensions, or content packs, this is where to go.

Not sure which repo to use? Pick your best guess, or submit to whichever repo feels closest. We can always move it to the right place.

Example: CaLab's issue system

CaLab is a good example of what a structured issue system looks like. It has issue templates set up so you don't have to start from a blank page. When you click "New issue," you'll see options like:

Bug Report — something isn't working correctly
Feature Request — suggest a new feature or improvement
General Feedback — share thoughts, suggestions, or general feedback
Field Option Request — request a new calcium indicator, species, or brain region option
Blank issue — write whatever you want from scratch

These templates guide you through providing the information we need without making it feel like a chore. Most fields are optional. The only required field in a bug report, for example, is a description of what happened.

How to submit an issue: a walkthrough

Here's the step-by-step process. It takes about 2 minutes.

Step 1: Go to the repository

Navigate to the GitHub repository for the tool you're using. For example, for CaLab: [1].

The main page of a GitHub repository. The Issues tab is visible in the navigation bar near the top.

Step 2: Click the Issues tab

Click on the Issues tab in the repository's navigation bar. You'll see a list of existing issues, both open and closed.

The Issues tab shows all open issues. You can also click "Closed" to see resolved issues. Notice that issues include bug reports, feature requests, and feedback from both the development team and community members.

Step 3: Click "New issue"

Click the green New issue button in the upper right corner.

Step 4: Choose a template

If the repository has issue templates set up (like CaLab does), you'll see a list of options. Pick the one that best fits what you want to say. If none of them fit, choose "Blank issue."

The issue template chooser. Pick whichever type fits best. Don't overthink it.

Step 5: Fill out the form

Fill in the fields. Write a short, descriptive title and then describe what happened, what you expected, or what you'd like to see. Don't worry about being too technical or too detailed. Something is always better than nothing.

A bug report form. The only required field is the Description. Steps to reproduce, browser/OS, and additional context are all optional but helpful if you have them.

Step 6: Submit

Click the green Submit new issue button at the bottom. That's it. You'll get notifications if someone responds.

Tips for writing a good issue

You don't need to write a novel. Here are some things that help us help you:

Be specific about what happened. "CaTune crashed" is okay. "CaTune froze when I loaded a 50,000-frame .npz file in Chrome on Windows" is better.
Include what you expected to happen. This helps us understand whether something is a bug or a design choice that could be improved.
Screenshots are worth a thousand words. You can paste screenshots directly into the issue form on GitHub. If you see an error, grab a screenshot.
Don't worry about format or polish. A rough, honest description is more useful than a perfectly formatted report that never gets written.
Don't search for duplicates first (unless you want to). We'd rather have two reports of the same bug than zero. If it's a duplicate, we'll link them together. No harm done.

Other ways to get help

Submitting a GitHub Issue is great for reporting problems and requesting features, but it's not the only way to engage with the Miniscope community:

Forum:Home — Ask questions, share your work, and discuss techniques with other Miniscope users.
FAQs — Check if your question has already been answered.
Events — We hold bi-monthly office hours where you can ask questions in real time, show us what's not working, or just say hi.

The bottom line

If something about a Miniscope tool confused you, frustrated you, or didn't work the way you expected, please tell us. You're not being a burden. You're helping us build better tools for everyone. The few minutes it takes to submit an issue can save hours of frustration for the next person who runs into the same thing.

And if you've been sitting on a problem because you weren't sure if it was "worth" reporting: it is.