22
33We'd love to accept your patches and contributions to this project.
44
5- - [ How to contribute] ( #how-to-contribute )
6- - [ Before you begin] ( #before-you-begin )
7- - [ Sign our Contributor License Agreement] ( #sign-our-contributor-license-agreement )
8- - [ Review our community guidelines] ( #review-our-community-guidelines )
9- - [ Contribution workflow] ( #contribution-workflow )
10- - [ Finding Issues to Work On] ( #finding-issues-to-work-on )
11- - [ Requirement for PRs] ( #requirement-for-prs )
12- - [ Large or Complex Changes] ( #large-or-complex-changes )
13- - [ Testing Requirements] ( #testing-requirements )
14- - [ Unit Tests] ( #unit-tests )
15- - [ Manual End-to-End (E2E) Tests] ( #manual-end-to-end-e2e-tests )
16- - [ Documentation] ( #documentation )
17- - [ Development Setup] ( #development-setup )
18- - [ Code reviews] ( #code-reviews )
5+ - [ How to contribute] ( #how-to-contribute )
6+ - [ Before you begin] ( #before-you-begin )
7+ - [ Sign our Contributor License Agreement] ( #sign-our-contributor-license-agreement )
8+ - [ Review our community guidelines] ( #review-our-community-guidelines )
9+ - [ Contribution workflow] ( #contribution-workflow )
10+ - [ Finding Issues to Work On] ( #finding-issues-to-work-on )
11+ - [ Requirement for PRs] ( #requirement-for-prs )
12+ - [ Large or Complex Changes] ( #large-or-complex-changes )
13+ - [ Testing Requirements] ( #testing-requirements )
14+ - [ Unit Tests] ( #unit-tests )
15+ - [ Manual End-to-End (E2E) Tests] ( #manual-end-to-end-e2e-tests )
16+ - [ Documentation] ( #documentation )
17+ - [ Development Setup] ( #development-setup )
18+ - [ Code reviews] ( #code-reviews )
1919
2020## Before you begin
2121
@@ -49,32 +49,31 @@ information on using pull requests.
4949
5050### Finding Issues to Work On
5151
52- - Browse issues labeled ** ` good first issue ` ** (newcomer-friendly) or ** `help
53- wanted`** (general contributions).
54- - For other issues, please kindly ask before contributing to avoid
55- duplication.
52+ - Browse issues labeled ** ` good first issue ` ** (newcomer-friendly) or ** ` help wanted ` ** (general contributions).
53+ - For other issues, please kindly ask before contributing to avoid
54+ duplication.
5655
5756### Requirement for PRs
5857
59- - All PRs, other than small documentation or typo fixes, should have an Issue
60- associated. If a relevant issue doesn't exist, please create one first or
61- you may instead describe the bug or feature directly within the PR
62- description, following the structure of our issue templates.
63- - Small, focused PRs. Keep changes minimal—one concern per PR.
64- - For bug fixes or features, please provide logs or screenshot after the fix
65- is applied to help reviewers better understand the fix.
66- - Please include a ` testing plan ` section in your PR to describe how you
67- will test. This will save time for PR review. See ` Testing Requirements `
68- section for more details.
58+ - All PRs, other than small documentation or typo fixes, should have an Issue
59+ associated. If a relevant issue doesn't exist, please create one first or
60+ you may instead describe the bug or feature directly within the PR
61+ description, following the structure of our issue templates.
62+ - Small, focused PRs. Keep changes minimal—one concern per PR.
63+ - For bug fixes or features, please provide logs or screenshot after the fix
64+ is applied to help reviewers better understand the fix.
65+ - Please include a ` testing plan ` section in your PR to describe how you
66+ will test. This will save time for PR review. See ` Testing Requirements `
67+ section for more details.
6968
7069### Large or Complex Changes
7170
7271For substantial features or architectural revisions:
7372
74- - Open an Issue First: Outline your proposal, including design considerations
75- and impact.
76- - Gather Feedback: Discuss with maintainers and the community to ensure
77- alignment and avoid duplicate work
73+ - Open an Issue First: Outline your proposal, including design considerations
74+ and impact.
75+ - Gather Feedback: Discuss with maintainers and the community to ensure
76+ alignment and avoid duplicate work
7877
7978### Testing Requirements
8079
@@ -88,16 +87,16 @@ passed `pytest` results.
8887
8988Requirements for unit tests:
9089
91- - ** Coverage:** Cover new features, edge cases, error conditions, and typical
92- use cases.
93- - ** Location:** Add or update tests under ` tests/unittests/ ` , following
94- existing naming conventions (e.g., ` test_<module>_<feature>.py ` ).
95- - ** Framework:** Use ` pytest ` . Tests should be:
96- - Fast and isolated.
97- - Written clearly with descriptive names.
98- - Free of external dependencies (use mocks or fixtures as needed).
99- - ** Quality:** Aim for high readability and maintainability; include
100- docstrings or comments for complex scenarios.
90+ - ** Coverage:** Cover new features, edge cases, error conditions, and typical
91+ use cases.
92+ - ** Location:** Add or update tests under ` tests/unittests/ ` , following
93+ existing naming conventions (e.g., ` test_<module>_<feature>.py ` ).
94+ - ** Framework:** Use ` pytest ` . Tests should be:
95+ - Fast and isolated.
96+ - Written clearly with descriptive names.
97+ - Free of external dependencies (use mocks or fixtures as needed).
98+ - ** Quality:** Aim for high readability and maintainability; include
99+ docstrings or comments for complex scenarios.
101100
102101#### Manual End-to-End (E2E) Tests
103102
@@ -107,20 +106,20 @@ is not impacted.
107106
108107Depending on your change:
109108
110- - ** ADK Web:**
109+ - ** ADK Web:**
111110
112- - Use the ` adk web ` to verify functionality.
113- - Capture and attach relevant screenshots demonstrating the UI/UX changes
114- or outputs.
115- - Label screenshots clearly in your PR description.
111+ - Use the ` adk web ` to verify functionality.
112+ - Capture and attach relevant screenshots demonstrating the UI/UX changes
113+ or outputs.
114+ - Label screenshots clearly in your PR description.
116115
117- - ** Runner:**
116+ - ** Runner:**
118117
119- - Provide the testing setup. For example, the agent definition, and the
120- runner setup.
121- - Execute the ` runner ` tool to reproduce workflows.
122- - Include the command used and console output showing test results.
123- - Highlight sections of the log that directly relate to your change.
118+ - Provide the testing setup. For example, the agent definition, and the
119+ runner setup.
120+ - Execute the ` runner ` tool to reproduce workflows.
121+ - Include the command used and console output showing test results.
122+ - Highlight sections of the log that directly relate to your change.
124123
125124### Documentation
126125
@@ -131,117 +130,118 @@ part before or alongside your code PR.
131130
132131## Development Setup
133132
134- 1 . ** Clone the repository:**
133+ 1 . ** Clone the repository:**
135134
136- ``` shell
137- gh repo clone google/adk-python
138- cd adk-python
139- ```
135+ ``` shell
136+ gh repo clone google/adk-python
137+ cd adk-python
138+ ```
140139
141- 2. ** Install uv:**
140+ 1 . ** Install uv:**
142141
143- Check out
144- [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
142+ Check out
143+ [ uv installation guide] ( https://docs.astral.sh/uv/getting-started/installation/ ) .
145144
146- 3. ** Create and activate a virtual environment:**
145+ 1 . ** Create and activate a virtual environment:**
147146
148- ** NOTE** : ADK supports Python 3.10+. Python 3.11 and above is strongly
149- recommended.
147+ ** NOTE** : ADK supports Python 3.10+. Python 3.11 and above is strongly
148+ recommended.
150149
151- Create a workspace venv using uv.
150+ Create a workspace venv using uv.
152151
153- ` ` ` shell
154- uv venv --python " python3.11" " .venv"
155- ` ` `
152+ ``` shell
153+ uv venv --python " python3.11" " .venv"
154+ ```
156155
157- Activate the workspace venv.
156+ Activate the workspace venv.
158157
159- ` ` ` shell
160- source .venv/bin/activate
161- ` ` `
158+ ``` shell
159+ source .venv/bin/activate
160+ ```
162161
163- ** Windows**
162+ ** Windows**
164163
165- ` ` ` shell
166- source .\. venv\S cripts\a ctivate
167- ` ` `
164+ ``` shell
165+ source .\. venv\S cripts\a ctivate
166+ ```
168167
169- 4. ** Install dependencies:**
168+ 1 . ** Install dependencies:**
170169
171- ` ` ` shell
172- uv sync --all-extras
173- ` ` `
170+ ``` shell
171+ uv sync --all-extras
172+ ```
174173
175- ** NOTE** : for convenience, installing all extra deps as a starting point.
174+ ** NOTE** : for convenience, installing all extra deps as a starting point.
176175
177- 5. ** Run unit tests:**
176+ 1 . ** Run unit tests:**
178177
179- ` ` ` shell
180- pytest ./tests/unittests
181- ` ` `
178+ ``` shell
179+ pytest ./tests/unittests
180+ ```
182181
183- NOTE: for accurate repro of test failure, only include ` test` as extra
184- dependencies.
182+ NOTE: for accurate repro of test failure, only include ` test ` as extra
183+ dependencies.
185184
186- ` ` ` shell
187- uv sync --extra test
188- pytest ./tests/unittests
189- ` ` `
185+ ``` shell
186+ uv sync --extra test
187+ pytest ./tests/unittests
188+ ```
190189
191- ** Alternatively** , use the included ` unittests.sh` script which handles
192- environment setup and restoration automatically:
190+ ** Alternatively** , use the included ` unittests.sh ` script which handles
191+ environment setup and restoration automatically:
193192
194- ` ` ` shell
195- ./scripts/unittests.sh
196- ` ` `
193+ ``` shell
194+ ./scripts/unittests.sh
195+ ```
197196
198- This script will:
199- - Set up the test environment with minimal dependencies (` test` , ` eval` , ` a2a` )
200- - Run the unit tests
201- - Restore the full development environment (` --all-extras` )
197+ This script will:
202198
203- 6. ** Auto-format the code:**
199+ - Set up the test environment with minimal dependencies (` test ` , ` eval ` , ` a2a ` )
200+ - Run the unit tests
201+ - Restore the full development environment (` --all-extras ` )
204202
205- ** NOTE** : We use ` isort` and ` pyink` for styles. Use the included
206- autoformat.sh to auto-format.
203+ 1 . ** Auto-format the code:**
207204
208- ` ` ` shell
209- ./autoformat.sh
210- ` ` `
205+ ** NOTE** : We use ` isort ` and ` pyink ` for styles. Use the included
206+ autoformat.sh to auto-format.
211207
212- 7. ** Build the wheel file:**
208+ ``` shell
209+ ./autoformat.sh
210+ ```
213211
214- ` ` ` shell
215- uv build
216- ` ` `
212+ 1 . ** Build the wheel file:**
217213
218- 8. ** Test the locally built wheel file: ** Have a simple testing folder setup as
219- mentioned in the
220- [quickstart](https://google.github.io/adk-docs/get-started/quickstart/).
214+ ``` shell
215+ uv build
216+ ```
221217
222- Then following below steps to test your changes:
218+ 1 . ** Test the locally built wheel file:** Have a simple testing folder setup as
219+ mentioned in the
220+ [ quickstart] ( https://google.github.io/adk-docs/get-started/quickstart/ ) .
223221
224- Create a clean venv and activate it :
222+ Then following below steps to test your changes :
225223
226- ` ` ` shell
227- VENV_PATH=~ /venvs/adk-quickstart
228- ` ` `
224+ Create a clean venv and activate it:
229225
230- ` ` ` shell
231- command -v deactivate > /dev/null 2>&1 && deactivate
232- ` ` `
226+ ``` shell
227+ VENV_PATH= ~ /venvs/adk-quickstart
228+ ```
233229
234- ` ` ` shell
235- rm -rf $VENV_PATH \
236- && python3 -m venv $VENV_PATH \
237- && source $VENV_PATH /bin/activate
238- ` ` `
230+ ``` shell
231+ command -v deactivate > /dev/null 2>&1 && deactivate
232+ ```
239233
240- Install the locally built wheel file:
234+ ``` shell
235+ rm -rf $VENV_PATH \
236+ && python3 -m venv $VENV_PATH \
237+ && source $VENV_PATH /bin/activate
238+ ```
241239
242- ` ` ` shell
243- pip install dist/google_adk-< version> -py3-none-any.whl
244- ` ` `
240+ Install the locally built wheel file:
241+
242+ ``` shell
243+ pip install dist/google_adk-< version> -py3-none-any.whl
244+ ```
245245
246246## Contributing Resources
247247
0 commit comments