Contributing to Formulate

Thank you for your interest in contributing to Formulate! This guide will help you get started with contributing to the project.

Setting Up Your Development Environment

  1. Fork the Repository

    Start by forking the Formulate repository on GitHub.

  2. Clone Your Fork

    git clone https://github.com/YOUR-USERNAME/formulate.git
cd formulate

  3. Set Up a Virtual Environment

    It’s recommended to use a virtual environment for development (e.g., venv, conda, uv etc.):

  4. Install Development Dependencies

    pip install -e ".[dev]"

  5. Set Up Pre-commit Hooks

    Formulate uses pre-commit hooks to ensure code quality:

    pip install pre-commit
pre-commit install

Development Workflow

  1. Create a Branch

    Create a new branch for your feature or bugfix:

    git checkout -b feature-or-bugfix-name

  2. Make Your Changes

    Implement your feature or fix the bug. Be sure to:

    • Follow the coding style of the project

    • Add tests for your changes

    • Update documentation if necessary

  3. Run Tests

    Make sure all tests pass:

    pytest

  4. Commit Your Changes

    Commit your changes with a descriptive commit message:

    git add .
git commit -m "Add feature X" or "Fix bug Y"

  5. Push Your Changes

    Push your changes to your fork:

    git push origin feature-or-bugfix-name

  6. Create a Pull Request

    Go to the Formulate repository and create a pull request from your branch.

Coding Guidelines

  1. Code Style

    Formulate follows the PEP 8 style guide. The pre-commit hooks will help ensure your code adheres to this style.

  2. Documentation

    • Document all public functions, classes, and methods using docstrings

    • Use type hints where appropriate

    • Update the documentation if you add new features or change existing ones

  3. Testing

    • Write tests for all new features and bug fixes

    • Ensure all tests pass before submitting a pull request

    • Aim for high test coverage

  4. Commit Messages

    • Write clear, concise commit messages

    • Start with a short summary line (50 chars or less)

    • Optionally, follow with a blank line and a more detailed explanation

Types of Contributions

There are many ways to contribute to Formulate:

  1. Bug Reports

    If you find a bug, please report it by creating an issue on GitHub. Include:

    • A clear description of the bug

    • Steps to reproduce the bug

    • Expected behavior

    • Actual behavior

    • Any relevant logs or error messages

  2. Feature Requests

    If you have an idea for a new feature, create an issue on GitHub describing:

    • What the feature would do

    • Why it would be useful

    • How it might be implemented

  3. Documentation Improvements

    Help improve the documentation by:

    • Fixing typos or errors

    • Clarifying explanations

    • Adding examples

    • Translating documentation

  4. Code Contributions

    Contribute code by:

    • Fixing bugs

    • Implementing new features

    • Improving performance

    • Refactoring code

  5. Reviewing Pull Requests

    Help review pull requests by:

    • Testing the changes

    • Reviewing the code

    • Providing constructive feedback