Skip to content
This repository was archived by the owner on Apr 17, 2026. It is now read-only.

CONTRIBUTING.md

Latest commit

 

History

History
300 lines (200 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

300 lines (200 loc) · 10.1 KB
Raw

Contributing to Maestro

Thank you for your interest in contributing to Maestro! This document provides guidelines and instructions for contributing to the project.

Requirements

Development Setup

  1. Fork in the cloud
  1. Clone the forked repository:
git clone https://github.com/<your-github-username>/maestro.git
cd maestro
  1. Configure upstream repo
git remote add upstream https://github.com/AI4quantum/maestro.git

# Never push to upstream main
git remote set-url --push upstream no_push

# Confirm that your remotes make sense:
git remote -v
  1. Activate the virtual environment:
uv venv --python 3.12
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows
  1. Install dependencies:
uv sync --all-extras
  1. (optional) Enable pre-commit
uv run pre-commit install

Development Workflow

  1. Create a new branch for your feature or bugfix:
git checkout -b feature/your-feature-name
  1. Make your changes and commit them:
git add .
git commit -m "feat: your feature description"
  1. Push your changes and create a pull request:
git push origin feature/your-feature-name

Code Style

We use ruff for code formatting and linting. To ensure your code meets our style guidelines:

  1. Install development dependencies:
uv sync
  1. Run the formatter:
uv run ruff format
  1. Run the linter:
uv run ruff check --fix

Commit Messages

We follow the Conventional Commits specification for commit messages. The format is:

<type>(<scope>): <subject>

<body>

<footer>

Types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code changes that neither fix bugs nor add features
  • perf: Performance improvements
  • test: Adding or modifying tests
  • chore: Changes to the build process or auxiliary tools

Example:

git commit -m "feat(agent): add new agent type"

Pull Request Process

  1. Ensure all dependencies are installed (uv sync).
  2. Run the test suite (uv run pytest).
  3. Run the formatter (uv run ruff format).
  4. Run the linter (uv run ruff check --fix).
  5. Update documentation if necessary.
  6. Create a pull request with a clear description of the changes.

Additional Resources

Before you start

If you are new to Maestro contributing, we recommend you do the following before diving into the code:

Style and lint

Maestro uses the following tools to meet code quality standards and ensure a unified code style across the codebase:

We use the following libs to check the Python code:

  • ruff - Code Formatter and Linter

Issues and pull requests

We use GitHub pull requests to accept contributions.

While not required, opening a new issue about the bug you're fixing or the feature you're working on before you open a pull request is important in starting a discussion with the community about your work. The issue gives us a place to talk about the idea and how we can work together to implement it in the code. It also lets the community know what you're working on, and if you need help, you can reference the issue when discussing it with other community and team members.

If you've written some code but need help finishing it, want to get initial feedback on it before finishing it, or want to share it and discuss it prior to completing the implementation, you can open a Draft pull request and prepend the title with the [WIP] tag (for Work In Progress). This will indicate to reviewers that the code in the PR isn't in its final state and will change. It also means we will only merge the commit once it is finished. You or a reviewer can remove the [WIP] tag when the code is ready to be thoroughly reviewed for merging.

Choose an issue to work on

Maestro uses the following labels to help non-maintainers find issues best suited to their interests and experience level:

  • good first issue - these issues are typically the simplest available to work on, ideal for newcomers. They should already be fully scoped, with a straightforward approach outlined in the descriptions.
  • help wanted - these issues are generally more complex than good first issues. They typically cover work that core maintainers don't currently have the capacity to implement and may require more investigation/discussion. These are great options for experienced contributors looking for something more challenging.

Set up a development environment

To start contributing to Maestro, follow these steps to set up your development environment:

  1. Set up Python environment: We recommend using Python 3.11 or higher. First, ensure you have Python installed:
python --version
  1. Activate a virtual environment: Activate a new virtual environment:
uv venv --python 3.12
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows
  1. Install dependencies: Install all project dependencies:
uv sync --all-extras

  1. Setup environmental variables: Make a copy of .env.example file in the repository's root and name it .env. Uncomment and update the parameters in the .env as needed.

  2. Follow Conventional Commit Messages: We use Conventional Commits to structure our commit messages. Please use the following format:

<type>(<scope>): <subject>
  • Type: feat, fix, chore, docs, style, refactor, perf, test, etc.
  • Scope: The area of the codebase your changes affect (optional). Examples: agents, workflow, cli, tests, etc.
  • Subject: A short description of the changes (required)

Example:

feat(agent): add new OpenAI agent type

Ref: #15
  1. Run Linter/Formatter: Ensure your changes meet code quality standards:
uv run ruff format
uv run ruff check --fix
  1. Run Tests: Ensure your changes pass all tests:
# Run all tests
uv run pytest
# Run specific test categories
uv run pytest tests/unit
uv run pytest tests/integration

  1. Commit:

    • commit: use the following command to sign-off your commit with -s:
git commit -s -m "<type>(<scope>): <subject>"

By following these steps, you'll be all set to contribute to our project! If you encounter any issues during the setup process, please feel free to open an issue.

Legal

The following sections detail important legal information that should be viewed prior to contribution.

License and Copyright

Distributed under the Apache License, Version 2.0.

SPDX-License-Identifier: Apache-2.0

If you would like to see the detailed LICENSE click here.

Developer Certificate of Origin (DCO)

We have tried to make it as easy as possible to make contributions. This applies to how we handle the legal aspects of contribution. We use the same approach - the Developer's Certificate of Origin 1.1 (DCO) - that the Linux® Kernel community uses to manage code contributions.

We ask that when submitting a patch for review, the developer must include a sign-off statement in the commit message. If you set your user.name and user.email in your git config file, you can sign your commit automatically by using the following command:

git commit -s

The following example includes a Signed-off-by: line, which indicates that the submitter has accepted the DCO:

Signed-off-by: John Doe <john.doe@example.com>

We automatically verify that all commit messages contain a Signed-off-by: line with your email address.

Useful tools for doing DCO signoffs

There are a number of tools that make it easier for developers to manage DCO signoffs.

Releases

A GitHub release of maestro is automatically created when a tag of the format v* is pushed.

The CI will automatically generate the build artifacts and changelog for the release, but will not make commits to the repo.

Preparation

Prior to creating a new release tag, the version needs to be updated in the pyproject.toml and README.md to match the version of the release tag.

Testing the release

To test the python package prior to release run the following command:

uv build

This will generate an installable package in dist/ that can be pip installed in a clean python environment for testing.

Container images

The release process generates 2 container images

  1. maestro: ghcr.io/ai4quantum/maestro

This image contains maestro executables. It can be used as the base image for the specific use case images.

  1. maestro-cli: ghcr.io/ai4quantum/maestro-cli

This image extends the maestro image to use as maestro CLI. It runs maestro command when it is started

The tools/buildimg.sh script generates development images. Run uv build before executing the script.