Skip to content

Contributing Guidelines

Back to Codebase Guide

Thank you for considering contributing to Commol! This document provides guidelines for contributing to the project.

How to Contribute

Reporting Bugs

Before creating a bug report:

  • Check the issue tracker for existing reports
  • Verify the bug exists in the latest version

Open the report from the template "Bug or small change" of .github/ISSUE_TEMPLATE/ (Planning), and include:

  • Clear title and description
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Environment details (OS, Python version, Commol version)
  • Code samples or test cases that demonstrate the problem

Suggesting Features

Feature suggestions are welcome! A feature becomes work as a proposal, an issue from the template "Proposal" (Planning). Please:

  • Check if the feature has already been requested
  • Provide a clear use case and rationale
  • Describe the desired API or interface
  • Consider implementation complexity vs benefit

Pull Requests

  1. Keep PRs focused: One feature/fix per PR
  2. Write tests: All new code should have tests
  3. Update docs (mandatory): Every change ships with its documentation. Follow the documentation definition of done
  4. Follow conventions: Use the project's code style
  5. Be descriptive: Write clear commit messages and PR descriptions
  6. Link the issue: The description says Closes #N for the issue it finishes

Development Guidelines

The rules for code, comments, documentation and commits are in one place: Conventions. In short:

Area Rule
Python Ruff (line length 88), type hints on every signature and never Any, NumPy docstrings on every public item
Rust cargo fmt, no Clippy warnings, rustdoc on every public item
Tests pytest for Python, laid out as in Tests; #[cfg(test)] modules and tests/ for Rust; test both success and error cases
Documentation Mandatory with every change: the definition of done
Commits type(scope): description, one short phrase, no body; see Commits

Run the checks of Quick commands before you open a pull request.

The pre-commit hooks run most of them on every commit; see Pre-commit Hooks.

Code Review Process

For Contributors

  1. Respond to feedback promptly and professionally
  2. Make requested changes or discuss alternatives
  3. Keep the PR updated with the target branch
  4. Test locally before requesting re-review

For Reviewers

  1. Be constructive and respectful
  2. Explain reasoning for requested changes
  3. Acknowledge good work when you see it
  4. Test the changes when possible

Release Process

See Release Process for details on versioning and releases.

Getting Help

Recognition

Contributors will be recognized in:

  • The project's AUTHORS file
  • Release notes for significant contributions
  • GitHub's contributor graph

Thank you for contributing to Commol! 🎉