Contributing to ToOp#

Thank you for your interest in contributing to ToOp! This guide will help you understand our development workflow and contribution process.

Local Development Setup#

We provide a Development Container configuration that sets up a complete development environment with all dependencies and tools pre-configured.

Prerequisites#

Docker installed and running
VS Code with the Dev Containers extension

Getting Started#

Clone the repository:

git clone https://github.com/eliagroup/ToOp.git
cd ToOp

Open in Dev Container:
- Open the repository in VS Code
- When prompted, click "Reopen in Container" or use Ctrl+Shift+P → "Dev Containers: Reopen in Container"
- Wait for the container to build and configure (first time may take several minutes)

What's Included#

The devcontainer automatically provides:

Python environment with all dependencies installed via uv sync
Pre-commit hooks automatically installed and configured
VS Code extensions for Python, Jupyter, Azure tools, and code quality
Docker-in-Docker for containerized workflows
Git configuration with safe directory setup
Testing suite based on pytest with VS Code testing integration.
- Run all tests: uv run pytest (this may take some time)
- Run some test: uv run pytest packages/<package_name>_pkg/tests

Contributing via Pull Requests#

We use trunk-based development, where main refers to the stable trunk branch containing all development and releases.

The contribution guidelines differ slightly between internal and external developers. As an external developer, you can fork our repository and contribute to code via pull requests. Make sure to name pull request according to our commit message standard as CI validation will fail otherwise.

Contributing with AI/LLM tools#

You may use AI coding assistants, but:

You are fully responsible for all contributed code, whether written manually or generated.
You must understand and be able to explain every submitted change.
A human must always review, validate, and approve the final contribution.
Do not use AI to interact with maintainers on your behalf. Improving grammar or clarity of your message is permitted.
Fully autonomous AI agents that open PRs without human review are not allowed and PRs will be rejected.

Acknowledgements#

This AI contribution guide is mainly based on SymPy and SciPy developers' AI policies. We thank them for their contribution.

Branching for Development#

You are advised to name branches in accordance with your goal. For that, we provide commit message types. For example, if you develop a new feature you can name your branch:

Feature Development: Create feature branches from main

git checkout main
git pull origin main
git checkout -b feat/your-feature-name

Bug Fixes: Create fix branches from main

git checkout main
git pull origin main
git checkout -b fix/fix-description

Standard PR workflow for external developers#

Fork and install:

git clone https://github.com/<your-username>/ToOp.git
cd ToOp
uv sync
pre-commit install

Add our repo to merge updates:

git remote add upstream https://github.com/eliagroup/ToOp.git

Create a branch from main:

git checkout main
git pull upstream main
git checkout -b feat/your-change

Implement and validate (tests + checks):

uv run pytest
pre-commit run --all-files

Sync with upstream before pushing to your fork:

git fetch upstream
git rebase upstream/main

Commit your change: We require Conventional Commits and Developer Certificate of Origin (DCO) for each commit to the main branch. Note that these commit messages are based on all commit messages within your PR, which will be squashed before a merge into main. You will make your life easier by adhering to conventional commits throughout all your commits. You can do so by using the -s flag when committing.
1 2
git add <files> git commit -s

Push to your fork and open a PR to main:

git push --set-upstream origin feat/your-change

Acceptance Criteria for PRs#

Single purpose: Each PR should contain one type of change - either a feature, a bugfix, or a refactor. Avoid mixing different types of changes in a single PR
PR description should be meaningful but concise. Use the following template:

Title of the pull request must conform to the conventional commit spec. It will be used for the squashed commit message of a PR.
Pull request squash commit message has to include Developer Certificate of Origin. Under some circumstances GitHub automatically adds author's signature, but in some cases it has to be added manually.
Code must pass all pre-commit hooks pre-commit run --all-files.
Tests must pass.
- Code coverage must be over 90% and aimed for 100%.
- Test locally by running uv run pytest
Documentation should be updated if needed

PR Commit Message Standards#

We require Conventional Commits and Developer Certificate of Origin (DCO) for each commit in the main branch. These commits are created when a pull request is squashed into the main branch.

Such a pull request's commit message must follow this format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Signed-off-by: FirstName LastName <something@example.org>

Commit Types#

feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code
refactor: A code change that neither fixes a bug nor adds a feature
perf: A code change that improves performance
test: Adding missing tests or correcting existing tests
chore: Changes to the build process or auxiliary tools

Developer Certificate of Origin#

The last line of the commit message certifies the origin of the code that will be committed. This means that you certify you have the rights to submit this work under this project's open source license (see Git docs).

Examples#

feat: add user authentication system

Signed-off-by: FirstName LastName <something@example.org>
---------------------------------------------------------

fix(api): resolve memory leak in data processing

Signed-off-by: FirstName LastName <something@example.org>
---------------------------------------------------------

docs: update installation instructions

Signed-off-by: FirstName LastName <something@example.org>

Commit Message Validation#

Commit messages are not validated but the final squashed commit of your PR will be. For that, we use Commitizen with the conventional commits standard.

Release Process#

Releases are managed through GitHub Actions and only generate Git tags. No commits are created during the release process.

Release Types#

Stable Releases (from main branch):
- Follow semantic versioning (e.g., v1.2.3)
- Used for production-ready code
Development Releases (from feature branches):
- Include a development identifier (e.g., v1.2.3.dev12345)
- Used for testing and preview purposes

Release Workflow#

The release process is automated through .github/workflows/release.yaml:

Manual Trigger: Releases are triggered manually via GitHub Actions
Version Calculation: Commitizen analyzes commit history to determine the next version
Tag Creation: A Git tag is created with the new version
Tag Push: The tag is pushed to the repository

Note: Releases only create Git tags. No packages are published to external registries.

Creating a Release#

Ensure your branch has the changes you want to release
Go to the GitHub Actions tab in the repository
Select the "release" workflow
Click "Run workflow" and select the appropriate branch
The workflow will automatically determine the next version and create a tag

Getting Help#

If you have questions about contributing:

Check existing issues and pull requests
Review the codebase documentation in the docs/ directory
Reach out to the maintainers

Thank you for contributing to ToOp! 🚀

License#

When you contribute to ToOp, you acknowledge and agree to the terms set out for any current and future contributions you provide.

All contributions will be licensed according to the license specified in the repository.