|
| 1 | +# How to contribute |
| 2 | + |
| 3 | +We'd love to accept your patches and contributions to this project. |
| 4 | + |
| 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 | + - [Code reviews](#code-reviews) |
| 10 | +- [Contribution workflow](#contribution-workflow) |
| 11 | + - [Finding Issues to Work On](#finding-issues-to-work-on) |
| 12 | + - [Requirement for PRs](#requirement-for-prs) |
| 13 | + - [Large or Complex Changes](#large-or-complex-changes) |
| 14 | + - [Testing Requirements](#testing-requirements) |
| 15 | + - [Unit Tests](#unit-tests) |
| 16 | + - [Manual End-to-End (E2E) Tests](#manual-end-to-end-e2e-tests) |
| 17 | + - [Documentation](#documentation) |
| 18 | + |
| 19 | +## Before you begin |
| 20 | + |
| 21 | +### Sign our Contributor License Agreement |
| 22 | + |
| 23 | +Contributions to this project must be accompanied by a |
| 24 | +[Contributor License Agreement](https://cla.developers.google.com/about) (CLA). |
| 25 | +You (or your employer) retain the copyright to your contribution; this simply |
| 26 | +gives us permission to use and redistribute your contributions as part of the |
| 27 | +project. |
| 28 | + |
| 29 | +If you or your current employer have already signed the Google CLA (even if it |
| 30 | +was for a different project), you probably don't need to do it again. |
| 31 | + |
| 32 | +Visit <https://cla.developers.google.com/> to see your current agreements or to |
| 33 | +sign a new one. |
| 34 | + |
| 35 | +### Review our community guidelines |
| 36 | + |
| 37 | +This project follows |
| 38 | +[Google's Open Source Community Guidelines](https://opensource.google/conduct/). |
| 39 | + |
| 40 | +### Code reviews |
| 41 | + |
| 42 | +All submissions, including submissions by project members, require review. We |
| 43 | +use GitHub pull requests for this purpose. Consult |
| 44 | +[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more |
| 45 | +information on using pull requests. |
| 46 | + |
| 47 | +## Contribution workflow |
| 48 | + |
| 49 | +### Finding Issues to Work On |
| 50 | + |
| 51 | +- Browse issues labeled **`good first issue`** (newcomer-friendly) or **`help |
| 52 | + wanted`** (general contributions). |
| 53 | +- For other issues, please kindly ask before contributing to avoid |
| 54 | + duplication. |
| 55 | + |
| 56 | +### Requirement for PRs |
| 57 | + |
| 58 | +- Code must follow [Google Go Style Guide](https://google.github.io/styleguide/go/index). |
| 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 screenshots after the fix |
| 65 | + is applied to help reviewers better understand the fix. |
| 66 | +- Please include a `testing plan` section in your PR to talk about how you |
| 67 | + will test. This will save time for PR review. See `Testing Requirements` |
| 68 | + section for more details. |
| 69 | + |
| 70 | +### Large or Complex Changes |
| 71 | + |
| 72 | +For substantial features or architectural revisions: |
| 73 | + |
| 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. |
| 78 | + |
| 79 | +### Testing Requirements |
| 80 | + |
| 81 | +To maintain code quality and prevent regressions, all code changes must include |
| 82 | +comprehensive tests and verifiable end-to-end (E2E) evidence. |
| 83 | + |
| 84 | +#### Unit Tests |
| 85 | + |
| 86 | +Please add or update unit tests for your change. |
| 87 | + |
| 88 | +Requirements for unit tests: |
| 89 | + |
| 90 | +- Cover new features, edge cases, error conditions, and typical |
| 91 | + use cases. |
| 92 | +- Fast and isolated. |
| 93 | +- Written clearly with descriptive names. |
| 94 | +- Free of external dependencies (use mocks or fixtures as needed). |
| 95 | +- Aim for high readability and maintainability; include comments for complex |
| 96 | + scenarios. |
| 97 | + |
| 98 | +#### Manual End-to-End (E2E) Tests |
| 99 | + |
| 100 | +Manual E2E tests ensure integrated flows work as intended. Your tests should |
| 101 | +cover all scenarios. Sometimes, it's also good to ensure relevant functionality |
| 102 | +is not impacted. |
| 103 | + |
| 104 | +Depending on your change: |
| 105 | + |
| 106 | +- **ADK Web:** |
| 107 | + |
| 108 | + - Capture and attach relevant screenshots demonstrating the UI/UX changes |
| 109 | + or outputs. |
| 110 | + - Label screenshots clearly in your PR description. |
| 111 | + |
| 112 | +- **Runner:** |
| 113 | + |
| 114 | + - Provide testing setup. For example, the agent definition, and the |
| 115 | + runner setup. |
| 116 | + - Include the command used and console output showing test results. |
| 117 | + - Highlight sections of the log that directly relate to your change. |
| 118 | + |
| 119 | +### Documentation |
| 120 | + |
| 121 | +For any changes that impact user-facing documentation (guides, API reference, |
| 122 | +tutorials), please open a PR in the |
| 123 | +[adk-docs](https://github.com/google/adk-docs) repository to update the relevant |
| 124 | +parts before or alongside your code PR. |
| 125 | + |
| 126 | +### Alignment with adk-python |
| 127 | +We lean on [adk-python](https://github.com/google/adk-python) for being the source of truth and one should refer to adk-python for validation. |
0 commit comments