Skip to content

Submitting Pull Requests

We appreciate your contributions. This guide covers our PR process to help your changes land smoothly.

Before You Start

  1. Check for existing issues — Someone may already be working on the same thing. Look through open issues and open PRs first.
  2. Open an issue for large changes — If you're planning a significant feature or refactor, open an issue to discuss the approach before writing code. This saves everyone time.

Creating Your PR

1. Create a feature branch

git checkout -b feature/your-feature-name

Use descriptive branch names:

  • feature/add-guardrail-evals for new features
  • fix/lint-rule-i007-false-positive for bug fixes
  • docs/improve-auth-guide for documentation

2. Make your changes

  • Keep commits focused — one logical change per commit.
  • Write clear commit messages that explain why, not just what.
  • Follow the code style guide.

3. Run checks locally

Before pushing, make sure everything passes:

ruff check src/ tests/       # Lint check
ruff format --check src/ tests/  # Format check
pytest                        # Run tests

If you changed documentation:

mkdocs build --strict  # Catches broken links and warnings

4. Push and create the PR

git push origin feature/your-feature-name

Then open a pull request on GitHub. In your PR description:

  • Summarize what changed — A brief explanation of the problem and your solution.
  • Link related issues — Use "Fixes #123" or "Relates to #456".
  • Describe how to test — Help reviewers verify your changes.

What Makes a Good PR

  • Small and focused — Smaller PRs are easier to review and less likely to introduce issues. If your change touches many files, consider splitting it into multiple PRs.
  • Tests included — New features should come with tests. Bug fixes should include a test that would have caught the bug.
  • Documentation updated — If your change affects the CLI, API, or user-facing behavior, update the relevant documentation.

Review Process

  1. A maintainer will review your PR, usually within a few business days.
  2. You may receive feedback requesting changes — this is normal and collaborative, not adversarial.
  3. Once approved, a maintainer will merge your PR.

Tips

  • If CI fails, check the logs carefully. Pre-commit hooks run ruff and pytest — the same checks you can run locally.
  • Don't force-push to a PR branch after review has started. It makes it harder for reviewers to see what changed.
  • If your PR has been open for a while without review, it's fine to leave a polite comment asking for attention.