diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f345a904..b0c0bd79 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,25 +2,24 @@
We'd love to accept your patches and contributions to this project.
-- [How to contribute](#how-to-contribute)
-- [Before you begin](#before-you-begin)
- - [Sign our Contributor License Agreement](#sign-our-contributor-license-agreement)
- - [Review our community guidelines](#review-our-community-guidelines)
-- [Contribution workflow](#contribution-workflow)
- - [Finding Issues to Work On](#finding-issues-to-work-on)
- - [Requirement for PRs](#requirement-for-prs)
- - [Large or Complex Changes](#large-or-complex-changes)
- - [Testing Requirements](#testing-requirements)
- - [Unit Tests](#unit-tests)
- - [Manual End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)
- - [Documentation](#documentation)
- - [Development Setup](#development-setup)
- - [Code reviews](#code-reviews)
+- [How to contribute](#how-to-contribute)
+- [Before you begin](#before-you-begin)
+ - [Sign our Contributor License Agreement](#sign-our-contributor-license-agreement)
+ - [Review our community guidelines](#review-our-community-guidelines)
+- [Contribution workflow](#contribution-workflow)
+ - [Finding Issues to Work On](#finding-issues-to-work-on)
+ - [Requirement for PRs](#requirement-for-prs)
+ - [Large or Complex Changes](#large-or-complex-changes)
+ - [Testing Requirements](#testing-requirements)
+ - [Unit Tests](#unit-tests)
+ - [Manual End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests)
+ - [Documentation](#documentation)
+ - [Development Setup](#development-setup)
+ - [Code reviews](#code-reviews)
+## Before you begin
-# Before you begin
-
-## Sign our Contributor License Agreement
+### Sign our Contributor License Agreement
Contributions to this project must be accompanied by a
[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
@@ -34,73 +33,102 @@ was for a different project), you probably don't need to do it again.
Visit to see your current agreements or to
sign a new one.
-## Review our community guidelines
+### Review our community guidelines
This project follows
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
-# Contribution workflow
+### Code reviews
-## Finding Issues to Work On
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
-- Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help wanted`** (general contributions).
-- For other issues, please kindly ask before contributing to avoid duplication.
+## Contribution workflow
+### Finding Issues to Work On
-## Requirement for PRs
+- Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help
+ wanted`** (general contributions).
+- For other issues, please kindly ask before contributing to avoid
+ duplication.
-- All PRs, other than small documentation or typo fixes, should have a Issue associated. If not, please create one.
-- 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 talk about how you will test. This will save time for PR review. See `Testing Requirements` section for more details.
+### Requirement for PRs
+
+- All PRs, other than small documentation or typo fixes, should have a Issue
+ associated. If not, please create one.
+- 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 talk about how you
+ will test. This will save time for PR review. See `Testing Requirements`
+ section for more details.
+
+### Large or Complex Changes
-## 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
+- 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
+### Testing Requirements
-To maintain code quality and prevent regressions, all code changes must include comprehensive tests and verifiable end-to-end (E2E) evidence.
+To maintain code quality and prevent regressions, all code changes must include
+comprehensive tests and verifiable end-to-end (E2E) evidence.
+#### Unit Tests
-### Unit Tests
-
-Please add or update unit tests for your change. Please include a summary of passed `pytest` results.
+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__.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.
+- **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__.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 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.
+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.
+- **ADK Web:**
-- **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.
+ - 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.
-## Documentation
+- **Runner:**
-For any changes that impact user-facing documentation (guides, API reference, tutorials), please open a PR in the [adk-docs](https://github.com/google/adk-docs) repository to update relevant part before or alongside your code PR.
+ - 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](https://github.com/google/adk-docs) repository to update relevant
+part before or alongside your code PR.
## Development Setup
+
1. **Clone the repository:**
```shell
@@ -110,11 +138,13 @@ For any changes that impact user-facing documentation (guides, API reference, tu
2. **Install uv:**
- Check out [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+ Check out
+ [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
3. **Create and activate a virtual environment:**
- **NOTE**: ADK supports Python 3.9+. Python 3.11 and above is strongly recommended.
+ **NOTE**: ADK supports Python 3.9+. Python 3.11 and above is strongly
+ recommended.
Create a workspace venv using uv.
@@ -128,10 +158,7 @@ For any changes that impact user-facing documentation (guides, API reference, tu
source .venv/bin/activate
```
- **windows**
- ```shell
- source .\.venv\Scripts\activate
- ```
+ **windows** `shell source .\.venv\Scripts\activate`
4. **Install dependencies:**
@@ -147,7 +174,7 @@ For any changes that impact user-facing documentation (guides, API reference, tu
pytest ./tests/unittests
```
- NOTE: for accurate repro of test failure, only include `test`, `eval` and
+ NOTE: for accurate repro of test failure, only include `test`, `eval` and
`a2a` as extra dependencies.
```shell
@@ -164,14 +191,14 @@ For any changes that impact user-facing documentation (guides, API reference, tu
./autoformat.sh
```
-7. **Build the wheel file:**
+7. **Build the wheel file:**
```shell
uv build
```
-8. **Test the locally built wheel file:**
- Have a simple testing folder setup as mentioned in the
+8. **Test the locally built wheel file:** Have a simple testing folder setup as
+ mentioned in the
[quickstart](https://google.github.io/adk-docs/get-started/quickstart/).
Then following below steps to test your changes:
@@ -200,16 +227,11 @@ For any changes that impact user-facing documentation (guides, API reference, tu
## Contributing Resources
-[Contributing folder](https://github.com/google/adk-python/tree/main/contributing) has resources that is helpful for contributors.
+[Contributing folder](https://github.com/google/adk-python/tree/main/contributing)
+has resources that is helpful for contributors.
+## Vibe Coding
-## Code reviews
-
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
-
-# Vibe Coding
-
-If you want to contribute by leveraging viber coding, the AGENTS.md (https://github.com/google/adk-python/tree/main/AGENTS.md) could be used as context to your LLM.
\ No newline at end of file
+If you want to contribute by leveraging viber coding, the AGENTS.md
+(https://github.com/google/adk-python/tree/main/AGENTS.md) could be used as
+context to your LLM.
\ No newline at end of file