Contributing Guidelines#

Thank you for taking the time to contribute to the CAPIBARA Collaboration! Whether you’re fixing a bug, improving documentation, or suggesting a feature — every contribution matters.

Please read our Code of Conduct to keep our community inclusive and respectful.

📌 Getting Started#

Prerequisites#

  1. Read the README of the repo to understand the project goals and setup

  2. Make sure Git is installed and set up

  3. Familiarize yourself with the GitHub flow

  4. Review our Governance Charter and Membership Agreement

🐛 Creating a Good Issue#

Before Creating an Issue#

  1. Check Existing Issues: Search open and closed issues to avoid duplicates

  2. Use Templates: If available, use the issue template appropriate for your concern

  3. Check Documentation: Ensure your question isn’t already answered in docs

Issue Requirements#

If you notice a bug or have an idea for a feature:

  • Title: Clear, descriptive title

  • Description: Detailed explanation of the problem or suggestion

  • Context: Operating system, software versions, etc.

  • Reproduction Steps: For bugs, specific steps to reproduce

  • Expected vs Actual: What should happen vs what actually happens

  • Screenshots: If applicable, include screenshots or error messages

  • Related Issues: Link to any related issues

Issue Assignment#

You can work on any issue that:

  • Hasn’t been assigned

  • Has the “help wanted” label

  • Is marked as “good first issue”

Always comment on the issue to let others know you’re working on it. This prevents duplicate work.

🚀 Making Contributions#

We welcome all types of contributions! Here’s how to make meaningful changes:

🔧 Local Setup#

  1. Fork the Repository

    # Click 'Fork' button on GitHub, then:
git clone https://github.com/<your-username>/<repo-name>.git
cd <repo-name>

  2. Create a New Branch

    git checkout -b <branch-type>/<short-description>
# Examples:
# git checkout -b fix/typo-in-readme
# git checkout -b feat/add-new-sensor-support
# git checkout -b docs/update-contributing-guide

  3. Set Up Development Environment

    # Check for environment setup instructions in README
# Common setup:
python -m venv venv # create virtual environment
source venv/bin/activate # activate virual environment
pip install -r requirements.txt # install the required packages

  4. Make Your Changes

    • Follow the project’s coding standards

    • Add tests for new functionalities

    • Update documentation as needed

    • Keep changes focused (one feature/fix per PR)

  5. Test You Changes

    # Run existing tests
pytest

# Run liners if available
flake8 .
black --check .

Commit Guidelines#

We follow conventional commits:

# Format: type(scope): description

# Examples:
git commit -m "fix(parser): handle null values in CSV import"
git commit -m "feat(api): add new endpoint for sensor data"
git commit -m "docs(readme): update installation instructions"
git commit -m "test(analysis): add unit tests for statistics module"

Commit Types

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation

  • style: Formatting, missing semi-colons, etc.

  • refactor: Code restructuring

  • test: Adding tests

  • chore: Maintenance tasks

**Keep Commits Atomic:

  • One logical change per commit

  • Commit often, push when ready

  • Write clear commit messages

🔄 Opening a Pull Request (PR)#

PR Creation#

  1. Go to your fork on GitHub and click “Compare & Pull Request”

  2. Complete the PR template with:

    • Summary of changes

    • Related issue numbers (e.g., Closes #123)

    • Testing performed

    • Screenshots (if UI changes)

  3. Enable “Allow edits from maintainers”

PR Requirements Checklist#

Before submitting, ensure:

  • Code follows project style guidelines

  • Tests pass locally

  • Documentation updated

  • No new linting errors

  • Commit messages follow conventions

  • PR addresses single concern (split large changes)

  • Changes are backward compatible (or document breaking changes)

  • License headers maintained in new files

Review Process#

  1. Automated Checks: CI/CD runs tests and linting

  2. Code Review: At least one maintainer reviews

  3. Feedback: Address review comments promptly

  4. Merge: After approval and all checks pass

Review Expectations:

  • Be respectful and constructive

  • Focus on code, not individuals

  • Explain reasoning for suggestions

  • Thank reviewers for their time

🎯 Contribution Areas#

Code Contributions#

  • Bug fixes

  • New features

  • Performance improvements

  • Test coverage

  • Refactoring

Documentation#

  • Tutorials and guides

  • API documentation

  • Translation

  • Example projects

  • README improvements

Design & UX#

  • UI/UX improvements

  • Graphics and diagrams

  • User research

  • Accessibility improvements

Community#

  • Answering questions

  • Reviewing PRs

  • Mentoring newcomers

  • Writing blog posts

  • Giving thanks

📊 Tracking Contributions#

For Students#

If contributing for academic credit:

  1. Notify Steering Committee of requirements

  2. Document hours and contributions

  3. Request supervisor coordination if needed

  4. Ensure compliance with institutional policies

Contribution Recognition#

All contributions are recognized through:

  • GitHub contributor graph

  • Publication acknowledgements

  • Annual contributor awards

  • Speaker opportunities

🛠️ Development Guidelines#

Code Style#

  • Follow language-specific conventions

  • Use meaningful variable names

  • Comment complex logic

  • Keep functions small and focused

Testing#

  • Write tests for new functionality

  • Maintain or improve test coverage

  • Test edge cases

  • Include integration tests where appropriate

Documentation#

  • Document public APIs

  • Update README for significant changes

  • Include examples

  • Keep documentation in sync with code

Dependencies#

  • Justify new dependencies

  • Check license compatibility

  • Keep dependencies updated

  • Document in DEPENDENCIES.md

❓ Getting Help#

Resources#

Contact Points#

  • Technical Questions: Repository maintainers

  • Governance Questions: Steering Committee

  • Code of Conduct: Contact Form

  • General Inquiries: GitHub Discussions

Meetings#

Check for meeting availability for specific members.

🙏 Acknowledgments#

Thank you for contributing to open science! Your work helps advance space science and supports student researchers worldwide.

Remember: Every contribution matters, no matter how small. Whether fixing a typo or building a new instrument, you’re helping make science more open and accessible.

These guidelines adapt to our growing community. Suggestions for improvement are always welcome via issues or pull requests.