Skip to content

Commit 1d2be43

Browse files
anubhav756anubhav756
authored
docs: Enhance DEVELOPER.md for improved contribution guidelines (#316)
* docs: Enhance DEVELOPER.md for improved contribution guidelines This PR significantly improves the `DEVELOPER.md` documentation across all Python SDK packages: `toolbox-core`, `toolbox-langchain`, and `toolbox-llamaindex`. The aim is to provide a more comprehensive, clear, and consistent guide for developers contributing to the project. These updates aim to streamline the onboarding experience for new contributors and ensure that existing contributors have access to clear, up-to-date guidelines for developing and maintaining the SDKs. * docs: Fix broken docs link in dev.md * docs: Add pypi package links * docs: Mention cloud build trigger in CI and Github actions section
1 parent 908b92c commit 1d2be43

File tree

3 files changed

+405
-15
lines changed

3 files changed

+405
-15
lines changed

‎packages/toolbox-core/DEVELOPER.md

Lines changed: 133 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,23 @@
11
# Development
22

3-
Below are the details to set up a development environment and run tests.
3+
Below are the details to set up a development environment and run tests for the
4+
`toolbox-core` package.
5+
6+
## Versioning
7+
8+
This library adheres to [Semantic Versioning](http://semver.org/). Releases are
9+
automated using [Release Please](https://github.com/googleapis/release-please),
10+
which analyzes commit messages to determine version bumps.
11+
12+
## Processes
13+
14+
### Conventional Commit Messages
15+
16+
This repository utilizes [Conventional
17+
Commits](https://www.conventionalcommits.org/) for structuring commit messages.
18+
This standard is crucial for the automated release process managed by [Release
19+
Please](https://github.com/googleapis/release-please?tab=readme-ov-file#how-should-i-write-my-commits),
20+
which parses your Git history to create GitHub and PyPI releases.
421

522
## Install
623
1. Clone the repository:
@@ -18,20 +35,131 @@ Below are the details to set up a development environment and run tests.
1835
```
1936
1. Make code changes and contribute to the SDK's development.
2037
> [!TIP]
21-
> Using `-e` option allows you to make changes to the SDK code and have
22-
> those changes reflected immediately without reinstalling the package.
38+
> Using `-e` option allows you to make changes to the SDK code and have those
39+
> changes reflected immediately without reinstalling the package.
40+
41+
## Testing
42+
43+
### Local Tests
44+
45+
To run tests locally, ensure you have the necessary dependencies and a running
46+
Toolbox service.
2347
24-
## Test
2548
1. Navigate to the package directory if needed:
2649
```bash
2750
cd mcp-toolbox-sdk-python/packages/toolbox-core
2851
```
29-
1. Install the SDK and test dependencies:
52+
1. Install the SDK and its test dependencies:
3053
```bash
3154
pip install -e .[test]
3255
```
56+
1. Ensure your [Toolbox
57+
service](https://github.com/googleapis/genai-toolbox?tab=readme-ov-file#getting-started)
58+
is running and accessible (e.g., at `http://localhost:5000`).
3359
1. Run tests and/or contribute to the SDK's development.
3460

3561
```bash
3662
pytest
3763
```
64+
65+
> [!TIP]
66+
> You can run specific test files or modules:
67+
> ```bash
68+
> pytest tests/test_client.py
69+
> ```
70+
71+
#### Authentication in Local Tests
72+
Integration tests involving authentication rely on environment variables for
73+
`TOOLBOX_URL`, `TOOLBOX_VERSION`, and `GOOGLE_CLOUD_PROJECT`. For local runs,
74+
you might need to mock or set up dummy authentication tokens. Refer to
75+
`tests/conftest.py` for how authentication tokens (`auth_token1`, `auth_token2`)
76+
are generated and used in the test environment. The `auth_methods.py` module
77+
provides helper functions for obtaining Google ID tokens.
78+
79+
### Code Coverage
80+
81+
Tests are configured with `pytest-cov` to measure code coverage. Ensure your
82+
changes maintain or improve coverage.
83+
84+
### Linting and Type Checking
85+
86+
The repository enforces code style and type adherence using `black`, `isort`,
87+
and `mypy`. To run these checks locally:
88+
89+
1. Install test dependencies as described in "Local Tests" section
90+
[above](#local-tests).
91+
1. Run the linters and type checker from the `packages/toolbox-core` directory:
92+
```bash
93+
black --check .
94+
isort --check .
95+
MYPYPATH='./src' mypy --install-types --non-interactive --cache-dir=.mypy_cache/ -p toolbox_core
96+
```
97+
98+
### CI and GitHub Actions
99+
100+
This repository uses GitHub Actions for CI. Linting, type-checking, Cloud Build
101+
triggers, and integration tests are run automatically on pull requests.
102+
103+
* **Linting and Type Checking:** Configured in `lint-toolbox-core.yaml`.
104+
* **Integration Tests:** Executed via Cloud Build, defined in
105+
`integration.cloudbuild.yaml`. These tests interact with a live Toolbox
106+
service instance.
107+
108+
**Triggering Tests on GitHub:** For external contributions, tests can be
109+
triggered manually by commenting `/gcbrun` on a pull request. The `tests: run`
110+
label can also be used to signal the CI system to run tests.
111+
112+
## Contribution Process
113+
114+
We welcome contributions to this project! Please review the following guidelines
115+
before submitting.
116+
117+
### Contributor License Agreement (CLA)
118+
119+
Contributions to this project must be accompanied by a [Contributor License
120+
Agreement](https://cla.developers.google.com/about) (CLA). This grants Google
121+
permission to use and redistribute your contributions.
122+
123+
### Code Reviews
124+
125+
All submissions, including those by project members, require review. We use
126+
[GitHub pull requests](https://help.github.com/articles/about-pull-requests/)
127+
for this purpose.
128+
129+
* Ensure your pull request clearly describes the changes you are making.
130+
* Ideally, your pull request should include code, tests, and updated
131+
documentation (if applicable) in a single submission.
132+
* Code style and linting checks will run automatically. Please ensure they pass
133+
before requesting a review.
134+
* A reviewer from the `@googleapis/senseai-eco` team will typically review your
135+
PR within 2-5 days and may request changes or approve it.
136+
137+
## Releases & Pipelines
138+
139+
This project uses `release-please` for automated releases.
140+
141+
* **Release Automation:** [Release
142+
Please](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/.github/release-please.yml)
143+
is configured to manage releases based on [Conventional
144+
Commits](#conventional-commit-messages). It creates release pull requests and
145+
tags.
146+
* **Published Packages:** The release pipeline produces Python packages,
147+
including:
148+
* [`toolbox-core`](https://pypi.org/project/toolbox-core/)
149+
* [`toolbox-langchain`](https://pypi.org/project/toolbox-langchain/)
150+
* [`toolbox-llamaindex`](https://pypi.org/project/toolbox-llamaindex/)
151+
* **Release Trigger:** Releases are typically triggered automatically based on
152+
merges to the `main` branch, as configured in `release-trigger.yml`.
153+
154+
## Support
155+
156+
If you encounter issues or have questions, please check the existing [GitHub
157+
Issues](https://github.com/googleapis/genai-toolbox/issues) for the main Toolbox
158+
project. If your issue is specific to one of the SDKs, please look for existing
159+
issues [here](https://github.com/googleapis/mcp-toolbox-sdk-python/issues) or
160+
open a new issue in this repository.
161+
162+
### Reporting Security Issues
163+
164+
For security-related concerns, please report them via
165+
[g.co/vulnz](https://g.co/vulnz).

‎packages/toolbox-langchain/DEVELOPER.md

Lines changed: 136 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,23 @@
11
# Development
22

3-
Below are the details to set up a development environment and run tests.
3+
Below are the details to set up a development environment and run tests for the
4+
`toolbox-langchain` package.
5+
6+
## Versioning
7+
8+
This library adheres to [Semantic Versioning](http://semver.org/). Releases are
9+
automated using [Release Please](https://github.com/googleapis/release-please),
10+
which analyzes commit messages to determine version bumps.
11+
12+
## Processes
13+
14+
### Conventional Commit Messages
15+
16+
This repository utilizes [Conventional
17+
Commits](https://www.conventionalcommits.org/) for structuring commit messages.
18+
This standard is crucial for the automated release process managed by [Release
19+
Please](https://github.com/googleapis/release-please?tab=readme-ov-file#how-should-i-write-my-commits),
20+
which parses your Git history to create GitHub and PyPI releases.
421

522
## Install
623
1. Clone the repository:
@@ -18,20 +35,134 @@ Below are the details to set up a development environment and run tests.
1835
```
1936
1. Make code changes and contribute to the SDK's development.
2037
> [!TIP]
21-
> Using `-e` option allows you to make changes to the SDK code and have
22-
> those changes reflected immediately without reinstalling the package.
38+
> Using `-e` option allows you to make changes to the SDK code and have those
39+
> changes reflected immediately without reinstalling the package.
40+
41+
## Testing
42+
43+
### Local Tests
44+
45+
To run tests locally, ensure you have the necessary dependencies and a running
46+
Toolbox service.
2347
24-
## Test
2548
1. Navigate to the package directory if needed:
2649
```bash
2750
cd mcp-toolbox-sdk-python/packages/toolbox-langchain
2851
```
29-
1. Install the SDK and test dependencies:
52+
1. Install the SDK and its test dependencies:
3053
```bash
3154
pip install -e .[test]
3255
```
56+
1. Ensure your [Toolbox
57+
service](https://github.com/googleapis/genai-toolbox?tab=readme-ov-file#getting-started)
58+
is running and accessible (e.g., at `http://localhost:5000`).
3359
1. Run tests and/or contribute to the SDK's development.
3460

3561
```bash
3662
pytest
3763
```
64+
65+
> [!TIP]
66+
> You can run specific test files or modules:
67+
> ```bash
68+
> pytest tests/test_client.py
69+
> ```
70+
71+
#### Authentication in Local Tests
72+
Integration tests involving authentication rely on environment variables for
73+
`TOOLBOX_URL`, `TOOLBOX_VERSION`, and `GOOGLE_CLOUD_PROJECT`. For local runs,
74+
you might need to mock or set up dummy authentication tokens. These tests
75+
leverage authentication methods from `toolbox-core`. Refer to
76+
`packages/toolbox-core/tests/conftest.py` for how authentication tokens
77+
(`auth_token1`, `auth_token2`) are generated and used in the test environment,
78+
and `packages/toolbox-core/src/toolbox_core/auth_methods.py` for helper
79+
functions for obtaining Google ID tokens.
80+
81+
### Code Coverage
82+
83+
Tests are configured with `pytest-cov` to measure code coverage. Ensure your
84+
changes maintain or improve coverage.
85+
86+
### Linting and Type Checking
87+
88+
The repository enforces code style and type adherence using `black`, `isort`,
89+
and `mypy`. To run these checks locally:
90+
91+
1. Install test dependencies as described in "Local Tests" section
92+
[above](#local-tests).
93+
1. Run the linters and type checker from the `packages/toolbox-langchain`
94+
directory:
95+
```bash
96+
black --check .
97+
isort --check .
98+
MYPYPATH='./src' mypy --install-types --non-interactive --cache-dir=.mypy_cache/ -p toolbox_langchain
99+
```
100+
101+
### CI and GitHub Actions
102+
103+
This repository uses GitHub Actions for CI. Linting, type-checking, Cloud Build
104+
triggers, and integration tests are run automatically on pull requests.
105+
106+
* **Linting and Type Checking:** Configured in `lint-toolbox-langchain.yaml`.
107+
* **Integration Tests:** Executed via Cloud Build, defined in
108+
`integration.cloudbuild.yaml`. These tests interact with a live Toolbox
109+
service instance.
110+
111+
**Triggering Tests on GitHub:** For external contributions, tests can be
112+
triggered manually by commenting `/gcbrun` on a pull request. The `tests: run`
113+
label can also be used to signal the CI system to run tests.
114+
115+
## Contribution Process
116+
117+
We welcome contributions to this project! Please review the following guidelines
118+
before submitting.
119+
120+
### Contributor License Agreement (CLA)
121+
122+
Contributions to this project must be accompanied by a [Contributor License
123+
Agreement](https://cla.developers.google.com/about) (CLA). This grants Google
124+
permission to use and redistribute your contributions.
125+
126+
### Code Reviews
127+
128+
All submissions, including those by project members, require review. We use
129+
[GitHub pull requests](https://help.github.com/articles/about-pull-requests/)
130+
for this purpose.
131+
132+
* Ensure your pull request clearly describes the changes you are making.
133+
* Ideally, your pull request should include code, tests, and updated
134+
documentation (if applicable) in a single submission.
135+
* Code style and linting checks will run automatically. Please ensure they pass
136+
before requesting a review.
137+
* A reviewer from the `@googleapis/senseai-eco` team will typically review your
138+
PR within 2-5 days and may request changes or approve it.
139+
140+
## Releases & Pipelines
141+
142+
This project uses `release-please` for automated releases.
143+
144+
* **Release Automation:** [Release
145+
Please](https://github.com/googleapis/mcp-toolbox-sdk-python/blob/main/.github/release-please.yml)
146+
is configured to manage releases based on [Conventional
147+
Commits](#conventional-commit-messages). It creates release pull requests and
148+
tags.
149+
* **Published Packages:** The release pipeline produces Python packages,
150+
including:
151+
* [`toolbox-core`](https://pypi.org/project/toolbox-core/)
152+
* [`toolbox-langchain`](https://pypi.org/project/toolbox-langchain/)
153+
* [`toolbox-llamaindex`](https://pypi.org/project/toolbox-llamaindex/)
154+
* **Release Trigger:** Releases are typically triggered automatically based on
155+
merges to the `main` branch, as configured in `release-trigger.yml`.
156+
157+
## Support
158+
159+
If you encounter issues or have questions, please check the existing [GitHub
160+
Issues](https://github.com/googleapis/genai-toolbox/issues) for the main Toolbox
161+
project. If your issue is specific to one of the SDKs, please look for existing
162+
issues [here](https://github.com/googleapis/mcp-toolbox-sdk-python/issues) or
163+
open a new issue in this repository.
164+
165+
### Reporting Security Issues
166+
167+
For security-related concerns, please report them via
168+
[g.co/vulnz](https://g.co/vulnz).

0 commit comments

Comments
 (0)