Skip to content

Commit 7012e0a

Browse files
docs: improve contributor guidance (#72)
* some improvements * Update DEVELOPER.md * Update DEVELOPER.md * Update packages/toolbox-core/DEVELOPER.md Co-authored-by: Anubhav Dhawan <[email protected]> * remove toolbox_url from env variables --------- Co-authored-by: Anubhav Dhawan <[email protected]>
1 parent 56907eb commit 7012e0a

File tree

1 file changed

+80
-8
lines changed

1 file changed

+80
-8
lines changed

packages/toolbox-core/DEVELOPER.md

Lines changed: 80 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,28 @@ This guide provides instructions for setting up your development environment to
44
contribute to the `@toolbox-sdk/core` package, which is part of the
55
`mcp-toolbox-sdk-js` monorepo.
66

7-
## Prerequisites
7+
## Versioning
8+
9+
This library adheres to [Semantic Versioning](http://semver.org/). Releases are
10+
automated using [Release Please](https://github.com/googleapis/release-please),
11+
which analyzes commit messages to determine version bumps.
12+
13+
## Processes
14+
15+
### Conventional Commit Messages
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 npm releases.
21+
22+
## Install
823

924
Before you begin, ensure you have the following installed:
1025

1126
* Node.js ([LTS version recommended](https://nodejs.org/en/download/))
1227

13-
## Setup
28+
### Setup
1429

1530
These steps will guide you through setting up the monorepo and this specific package for development.
1631

@@ -51,7 +66,7 @@ These steps will guide you through setting up the monorepo and this specific pac
5166
This creates a symbolic link, allowing changes in `@toolbox-sdk/core` to be
5267
immediately reflected in the consuming project without reinstallation.
5368

54-
Don't forget to npm unlink / yarn unlink when done!
69+
Don't forget to `npm unlink` when done!
5570
5671
## Testing
5772
@@ -72,6 +87,13 @@ Ensure all tests pass before submitting your changes. Tests are typically run fr
7287
npm run test:e2e
7388
```
7489
90+
#### Authentication in Local Tests
91+
Integration tests involving authentication rely on environment variables for `TOOLBOX_VERSION`, and `GOOGLE_CLOUD_PROJECT`. For local runs,
92+
you might need to mock or set up dummy authentication tokens. Refer to
93+
[authTokenGetter](./test/e2e/test.e2e.ts#L214) for how authentication tokens (`authToken1`, `authToken2`)
94+
are generated and used in the test environment. The `authMethods.ts` module
95+
provides helper functions for obtaining Google ID tokens.
96+
7597
## Linting and Formatting
7698
7799
This project uses linters (e.g., ESLint) and formatters (e.g., Prettier) to maintain code quality and consistency.
@@ -89,16 +111,66 @@ This project uses linters (e.g., ESLint) and formatters (e.g., Prettier) to main
89111
```bash
90112
npm run fix
91113
```
114+
## Contribution Process
92115
93-
## Committing Changes
116+
We welcome contributions to this project! Please review the following guidelines
117+
before submitting.
118+
119+
### Contributor License Agreement (CLA)
120+
121+
Contributions to this project must be accompanied by a [Contributor License
122+
Agreement](https://cla.developers.google.com/about) (CLA). This grants Google
123+
permission to use and redistribute your contributions.
124+
125+
### Committing Changes
94126
95127
* **Branching:** Create a new branch for your feature or bug fix (e.g., `feature/my-new-feature` or `fix/issue-123`).
96128
* **Commit Messages:** Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit message conventions.
97129
* **Pre-submit checks:** On any PRs, presubmit checks like linters, unit tests
98130
and integration tests etc. are run. Make sure all checks are green before
99131
proceeding.
100-
* **Submitting a PR:** On approval by a repo maintainer, *Squash and Merge* your PR.
101-
102-
## Further Information
103132
104-
* If you encounter issues or have questions, please open an [issue](https://github.com/googleapis/mcp-toolbox-sdk-js/issues) on the GitHub repository.
133+
### Code Reviews
134+
135+
All submissions, including those by project members, require review. We use
136+
[GitHub pull requests](https://help.github.com/articles/about-pull-requests/)
137+
for this purpose.
138+
139+
* Ensure your pull request clearly describes the changes you are making.
140+
* Ideally, your pull request should include code, tests, and updated
141+
documentation (if applicable) in a single submission.
142+
* Code style and linting checks will run automatically. Please ensure they pass
143+
before requesting a review.
144+
* A reviewer from the maintainer team will typically review your
145+
PR within 2-5 days and may request changes or approve it.
146+
* On approval by a repo maintainer, *Squash and Merge* your PR.
147+
148+
## Releases & Pipelines
149+
150+
This project uses `release-please` for automated releases.
151+
152+
* **Release Automation:** [Release
153+
Please](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/.github/release-please.yml)
154+
is configured to manage releases based on [Conventional
155+
Commits](#conventional-commit-messages). It creates release pull requests and
156+
tags.
157+
* **Published Packages:** The release pipeline produces npm package(s),
158+
including:
159+
* `@toolbox-sdk/core`
160+
These packages are published to
161+
[npm](https://www.npmjs.com/).
162+
* **Release Trigger:** Releases are typically triggered automatically based on
163+
merges to the `main` branch, as configured in [release-trigger.yml](https://github.com/googleapis/mcp-toolbox-sdk-js/blob/main/.github/release-trigger.yml).
164+
165+
## Support
166+
167+
If you encounter issues or have questions, please check the existing [GitHub
168+
Issues](https://github.com/googleapis/genai-toolbox/issues) for the main Toolbox
169+
project. If your issue is specific to one of the SDKs, please look for existing
170+
issues [here](https://github.com/googleapis/mcp-toolbox-sdk-js/issues) or
171+
open a new issue in this repository.
172+
173+
### Reporting Security Issues
174+
175+
For security-related concerns, please report them via
176+
[g.co/vulnz](https://g.co/vulnz).

0 commit comments

Comments
 (0)