Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
298 lines (218 loc) · 9.95 KB

CONTRIBUTING.md

File metadata and controls

298 lines (218 loc) · 9.95 KB
Raw

📍 Contributing — read this first

This is vidaiUK/adk-python, a fork of google/adk-python. Where your change belongs depends on what it is:

Your change is… Send it to What to do
A fix or feature for ADK itself Upstream — google/adk-python Follow the Google process below (CLA required). Do not PR it here.
Specific to this fork's feature (env-var base_url resolution — see FORK.md) Here — vidaiUK/adk-python Open an issue/PR against the main branch. No CLA.
You're not sure Here, as an issue Open an issue and we'll route it.

Why two destinations: this fork deliberately carries only the base_url env-var change. Everything else is stock ADK and flows in automatically from upstream via the daily sync (FORK.md) — so general ADK improvements are far more valuable upstream, where everyone gets them.

Working on the fork feature:

  1. Branch from main. 2. Keep the change scoped to base_url resolution.
  2. Add/update tests under tests/unittests/models/. 4. Open a PR to main; fork-ci must be green. 5. Once merged and green, the daily sync promotes it to the stable branch that consumers pin.

The Google process below applies only to upstream-bound contributions.

How to contribute

We'd love to accept your patches and contributions to this project.

Before you begin

Sign our Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.

If you or your current employer have already signed the Google CLA (even if it was for a different project), you probably don't need to do it again.

Visit https://cla.developers.google.com/ to see your current agreements or to sign a new one.

Review our community guidelines

This project follows Google's Open Source Community Guidelines.

Code reviews

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Contribution workflow

Finding Issues to Work On

  • Browse issues labeled good first issue (newcomer-friendly) or help wanted (general contributions).
  • For other issues, please kindly ask before contributing to avoid duplication.

Requirement for PRs

  • All PRs, other than small documentation or typo fixes, should have an Issue associated. If a relevant issue doesn't exist, please create one first or you may instead describe the bug or feature directly within the PR description, following the structure of our issue templates.
  • Small, focused PRs. Keep changes minimal—one concern per PR.
  • For bug fixes or features, please provide logs or screenshot after the fix is applied to help reviewers better understand the fix.
  • Please include a testing plan section in your PR to describe how you will test. This will save time for PR review. See Testing Requirements section for more details.

Large or Complex Changes

For substantial features or architectural revisions:

  • Open an Issue First: Outline your proposal, including design considerations and impact.
  • Gather Feedback: Discuss with maintainers and the community to ensure alignment and avoid duplicate work

Testing Requirements

To maintain code quality and prevent regressions, all code changes must include comprehensive tests and verifiable end-to-end (E2E) evidence.

Unit Tests

Please add or update unit tests for your change. Please include a summary of passed pytest results.

Requirements for unit tests:

  • Coverage: Cover new features, edge cases, error conditions, and typical use cases.
  • Location: Add or update tests under tests/unittests/, following existing naming conventions (e.g., test_<module>_<feature>.py).
  • Framework: Use pytest. Tests should be:
    • Fast and isolated.
    • Written clearly with descriptive names.
    • Free of external dependencies (use mocks or fixtures as needed).
  • Quality: Aim for high readability and maintainability; include docstrings or comments for complex scenarios.

Manual End-to-End (E2E) Tests

Manual E2E tests ensure integrated flows work as intended. Your tests should cover all scenarios. Sometimes, it's also good to ensure relevant functionality is not impacted.

Depending on your change:

  • ADK Web:

    • Use the adk web to verify functionality.
    • Capture and attach relevant screenshots demonstrating the UI/UX changes or outputs.
    • Label screenshots clearly in your PR description.

  • Runner:

    • Provide the testing setup. For example, the agent definition, and the runner setup.
    • Execute the runner tool to reproduce workflows.
    • Include the command used and console output showing test results.
    • Highlight sections of the log that directly relate to your change.

Documentation

For any changes that impact user-facing documentation (guides, API reference, tutorials), please open a PR in the adk-docs repository to update the relevant part before or alongside your code PR.

Development Setup

  1. Clone the repository:

    gh repo clone google/adk-python
cd adk-python

  2. Install uv:

    Check out uv installation guide.

  3. Setup Development Tools:

    We use pre-commit for code formatting and license enforcement, tox with tox-uv for isolated multi-version testing, and addlicense for Apache 2.0 license headers.

    uv tool install pre-commit
uv tool install tox --with tox-uv

    Optionally, install Google's addlicense tool for license header checks (requires Go):

    go install github.com/google/addlicense@latest

    If addlicense is not installed, the pre-commit hook will be skipped and CI will catch missing headers.

    Install the git hooks to automatically format and check your code before committing:

    pre-commit install

    The pre-commit hooks run isort, pyink, addlicense, and mdformat automatically on each commit.

  4. Create virtual environment and install dependencies:

    uv venv --python "python3.11" ".venv"
source .venv/bin/activate
uv sync --all-extras

  5. Run unit tests locally (Fast):

    If you just want to run tests quickly while developing, run pytest:

    pytest ./tests/unittests

  6. Run multi-version unit tests (Required before PR):

    ADK guarantees compatibility across Python versions. You must run the full test suite across all supported versions using tox. This will execute tests in pristine, isolated environments.

    tox

    (Note: uv will automatically download any Python interpreters you are missing!)

  7. Auto-format the code:

    If you installed the git hooks in Step 3, this happens automatically on commit. To run it manually across all files:

    pre-commit run --all-files

  8. Build the wheel file:

    uv build

  9. Test the locally built wheel file: Have a simple testing folder setup as mentioned in the quickstart.

    Then following below steps to test your changes:

    Create a clean venv and activate it:

    VENV_PATH=~/venvs/adk-quickstart
    command -v deactivate >/dev/null 2>&1 && deactivate
    rm -rf $VENV_PATH \
  && python3 -m venv $VENV_PATH \
  && source $VENV_PATH/bin/activate

    Install the locally built wheel file:

    pip install dist/google_adk-<version>-py3-none-any.whl

Contributing Resources

Contributing folder has resources that are helpful for contributors.

AI-Assisted Development

This repo includes built-in skills for AI coding agents (Antigravity, Gemini CLI, and others) to help with ADK development:

  • setup-dev-env — Set up the local development environment: install dependencies, configure pre-commit hooks, and verify the setup.

  • adk-debug — Debug ADK agents: inspect sessions, trace event flows, check LLM requests/responses, diagnose tool call issues. Supports both adk web (browser UI) and adk run (CLI) workflows.

  • adk-workflow — Build graph-based workflow agents: function nodes, LLM agent nodes, edge patterns, routing, parallel processing (fan-out and ParallelWorker), human-in-the-loop, state management, and best practices. Includes reference docs and tested samples.

These skills are in .agents/skills/ and are automatically available when using compatible AI coding tools in this repo.

The AGENTS.md file provides additional project context that can be used as LLM input.