mirror of
https://github.com/encounter/adk-python.git
synced 2026-07-09 18:19:28 -07:00
chore: update contribution guide
PiperOrigin-RevId: 804985449
This commit is contained in:
Hangfei Lin
committed by
Copybara-Service
Copybara-Service
parent
a645580aa6
commit
8174a29c6d
+98
-76
@@ -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 <https://cla.developers.google.com/> 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_<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.
|
||||
- **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 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.
|
||||
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.
|
||||
Reference in New Issue
Block a user