Contributing to asimov

We welcome contributions from the community! Learn how you can help make gravitational-wave analysis better for everyone.

Ways to Contribute

Report Bugs

Found a bug? Report it on GitHub Issues. Include detailed steps to reproduce, expected behavior, and system information.

Report Issue
Suggest Features

Have an idea for a new feature? Open a feature request on GitHub. Describe the use case and how it would help researchers.

Suggest Feature
Improve Documentation

Help make our documentation clearer, fix typos, or add examples. Good documentation is crucial for usability.

View Docs
Write Code

Submit pull requests to fix bugs, add features, or improve performance. All code contributions are reviewed and tested.

View Repositories
Add Tests

Improve code coverage by writing unit tests. Tests ensure reliability and make it easier to refactor code safely.

Share Your Experience

Write tutorials, blog posts, or examples showing how you use asimov in your research.

Getting Started

1. Set Up Your Development Environment

Fork the repository and clone it locally:

git clone https://github.com/YOUR_USERNAME/asimov.git
cd asimov
pip install -e .[dev]

The [dev] extra installs development dependencies including testing frameworks and linters.

2. Create a Branch

Create a new branch for your work:

git checkout -b feature/your-feature-name

Use descriptive branch names like feature/add-new-sampler or bugfix/fix-config-parsing.

3. Make Your Changes

Write your code following our coding standards:

  • Follow PEP 8 style guidelines for Python code
  • Write docstrings using the numpydoc format
  • Add unit tests for new functionality using unittest framework
  • Keep changes focused and atomic
  • Write clear, descriptive commit messages
4. Run Tests

Ensure all tests pass before submitting:

python -m unittest discover

Run linters to check code style:

flake8 .
black --check .
5. Submit a Pull Request

Push your changes and open a pull request:

git push origin feature/your-feature-name

In your pull request description:

  • Describe what changes you made and why
  • Reference any related issues (e.g., "Fixes #123")
  • Explain how you tested your changes
  • Note any breaking changes

Code Standards

Python Style

We follow PEP 8 conventions. Key points:

  • Use 4 spaces for indentation (no tabs)
  • Maximum line length of 88 characters (Black default)
  • Use descriptive variable names
  • Use type hints where appropriate
Documentation

All public functions, classes, and modules must have docstrings using the numpydoc format:

def example_function(param1, param2):
    """
    Brief description of function.

    Longer description if needed.

    Parameters
    ----------
    param1 : type
        Description of param1.
    param2 : type
        Description of param2.

    Returns
    -------
    type
        Description of return value.
    """
Testing

We use the unittest framework for testing. Key principles:

  • Write tests for all new functionality
  • Aim for high code coverage (>80%)
  • Test edge cases and error conditions
  • Keep tests focused and independent
  • Use descriptive test names that explain what is being tested
Command Line Interfaces

For command line interfaces, we use the Click framework. Ensure CLIs are well-documented with help text and examples.

Code Review Process

All contributions go through a code review process to maintain quality and consistency:

  1. Submit Pull Request - Open a PR with your changes
  2. Automated Checks - CI/CD runs tests and linters automatically
  3. Code Review - Maintainers review your code and provide feedback
  4. Address Feedback - Make requested changes and push updates
  5. Approval - Once approved, a maintainer will merge your PR
Be patient! Maintainers are often busy researchers. It may take some time to review your contribution. Feel free to politely ping after a week if you haven't received feedback.

Community Guidelines

The asimov community is committed to providing a welcoming and inclusive environment for all contributors. We expect all participants to:

  • Be respectful and considerate in all interactions
  • Welcome newcomers and help them get started
  • Focus on what is best for the community and the science
  • Show empathy towards other community members
  • Accept constructive criticism gracefully
  • Avoid demeaning, discriminatory, or harassing behavior

By contributing to asimov, you agree to abide by these community guidelines and our code of conduct.

Questions?

If you have questions about contributing or need help getting started:

GitHub Discussions

Ask questions and discuss ideas in GitHub Discussions

Open an Issue

For specific bugs or features, open an issue on GitHub

Ready to Contribute?

Help us make gravitational-wave analysis fun, easy, and reproducible!

View Repositories on GitHub