@devries-cameron20 / composio Mirror · read-only / commits / f254d1333
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 19:45 UTC

docs: update contributing guide for current repo (#3651)

This PR: - supersedes https://github.com/ComposioHQ/composio/pull/3535 and credits @eldar702 for the original `CONTRIBUTING.md` refresh - closes https://github.com/ComposioHQ/composio/issues/3487 - refreshes the repo layout around `ts/`, `python/`, `docs/`, and root release/install tests - documents the current `mise.toml` toolchain and removes stale Corepack, `.nvmrc`, `.bun-version`, and top-level `packages/` guidance - replaces the strict file-header requirement with current TypeScript/Python coding standards - adds current TypeScript e2e, Python, docs-site, changeset, and release-doc pointers - verifies documented paths, package scripts, Python make targets, Prettier, and whitespace checks locally Co-authored-by: Eldar Shlomi <eldarshlomi7@gmail.com>

Alberto Schiabel committed Jun 24, 2026 at 21:32 UTC f254d1333a1c399aff20b98bab78c49bfac378b2
1 file changed +198 -233
CONTRIBUTING.md
+198 -233
@@ -1,25 +1,40 @@
1 # Contributing to Composio SDK
2
3 -Thank you for your interest in contributing to Composio SDK! This document provides guidelines and instructions for contributing to the project.
3 +Thank you for your interest in contributing to Composio. This guide covers the root SDK repository. The monorepo contains the TypeScript SDK, Python SDK, docs site, examples, and release tooling.
4
5 ## Table of Contents
6
7 - [Development Setup](#development-setup)
8 - [Project Structure](#project-structure)
9 +- [Development Commands](#development-commands)
10 - [Coding Standards](#coding-standards)
11 - [Documentation Requirements](#documentation-requirements)
12 - [Pull Request Process](#pull-request-process)
13 - [Creating New Providers](#creating-new-providers)
14 - [Testing Guidelines](#testing-guidelines)
15 - [Release Process](#release-process)
16 +- [Questions and Support](#questions-and-support)
17
18 ## Development Setup
19
20 ### Prerequisites
21
20 -- Node.js (Latest LTS version recommended)
21 -- [pnpm](https://pnpm.io/) (v10.8.0 or later)
22 -- [bun](https://bun.sh) for productivity (optional)
22 +Tool versions are pinned in [`mise.toml`](mise.toml), which is the source of truth for local development and CI:
23 +
24 +- Node.js 24.17.0
25 +- pnpm 11.8.0
26 +- Bun 1.3.10
27 +- Deno 2.6.7
28 +- Python 3.12
29 +- uv 0.8.19
30 +
31 +Use [mise](https://mise.jdx.dev) to install the toolchain:
32 +
33 +```bash
34 +mise install
35 +```
36 +
37 +pnpm is installed through mise's npm backend. Do not rely on Corepack for this repository.
38
39 ### Getting Started
40
@@ -30,39 +45,79 @@ Thank you for your interest in contributing to Composio SDK! This document provi
45 cd composio
46 ```
47
33 -2. Install dependencies:
48 +2. Install the pinned toolchain:
49 +
50 + ```bash
51 + mise install
52 + ```
53 +
54 +3. Install dependencies:
55
56 ```bash
57 pnpm install
58 ```
59
39 -3. Build the project:
60 +4. Build the project:
61
62 ```bash
63 pnpm build
64 ```
65
45 -4. Run tests:
66 +5. Run tests:
67 +
68 ```bash
69 pnpm test
70 ```
71
50 -### Development Commands
72 +## Project Structure
73 +
74 +```text
75 +composio/
76 +├── ts/ # TypeScript SDK workspace
77 +│ ├── packages/
78 +│ │ ├── core/ # Core SDK package (@composio/core)
79 +│ │ ├── cli/ # CLI binary and command implementations
80 +│ │ ├── cli-keyring/ # Keyring helper for the CLI
81 +│ │ ├── cli-local-tools/ # Local tools support for the CLI
82 +│ │ ├── providers/ # AI framework provider adapters
83 +│ │ ├── json-schema-to-zod/ # Schema conversion utility
84 +│ │ └── ts-builders/ # TypeScript build helpers
85 +│ ├── e2e-tests/ # Runtime and CLI end-to-end tests
86 +│ ├── examples/ # TypeScript examples
87 +│ └── scripts/ # TypeScript build and maintenance scripts
88 +├── python/ # Python SDK
89 +│ ├── composio/ # Main Python package
90 +│ ├── providers/ # Python provider adapters
91 +│ ├── tests/ # pytest test suite
92 +│ ├── scripts/ # Python development and release scripts
93 +│ └── docs/ # Python release notes and process docs
94 +├── docs/ # Documentation site
95 +├── test/ # Root-level release/install script tests
96 +└── .github/ # GitHub Actions and shared CI actions
97 +```
98 +
99 +## Development Commands
100
101 ```bash
53 -# Lint code
102 +# Build all packages
103 +pnpm build
104 +
105 +# Build TypeScript packages only
106 +pnpm build:packages
107 +
108 +# Lint TypeScript packages
109 pnpm lint
110
56 -# Fix linting issues
111 +# Fix lint issues where possible
112 pnpm lint:fix
113
59 -# Format code
114 +# Format supported files
115 pnpm format
116
62 -# Create a new provider
117 +# Create a new TypeScript provider
118 pnpm create:provider <provider-name> [--agentic]
119
65 -# Create a new example
120 +# Create a new TypeScript example
121 pnpm create:example <example-name>
122
123 # Check peer dependencies
@@ -72,281 +127,191 @@ pnpm check:peer-deps
127 pnpm update:peer-deps
128 ```
129
75 -## Project Structure
130 +## Coding Standards
131
77 -```
78 -composio/
79 -├── packages/ # Main packages directory
80 -│ ├── core/ # Core SDK package
81 -│ └── providers/ # Provider implementations
82 -├── examples/ # Example implementations
83 -├── docs/ # Documentation
84 -├── scripts/ # Development and build scripts
85 -└── .github/ # GitHub configuration
86 -```
132 +### TypeScript
133
88 -## Coding Standards
134 +1. Follow the style of the package you are editing.
135 +2. Use TypeScript for new TypeScript SDK code.
136 +3. Use named exports for public APIs unless the local package pattern says otherwise.
137 +4. Keep public API changes typed and documented with TSDoc.
138 +5. Add focused tests for new behavior and bug fixes.
139 +6. Use ESLint and Prettier through the repo scripts.
140 +7. Keep generated or vendored code out of manual edits unless the package explicitly owns that output.
141
90 -### File Headers
91 -
92 -Every source file must include a header comment with:
93 -
94 -```typescript
95 -/**
96 - * @file Description of what this file does/contains
97 - * @module path/to/module
98 - * @description Detailed description of the file's purpose
99 - *
100 - * @author Original Author <email@example.com>
101 - * @contributors
102 - * - Contributor Name <email@example.com>
103 - *
104 - * @copyright Composio 2024
105 - * @license ISC
106 - *
107 - * @see {@link https://related.documentation.link}
108 - * @see {@link https://another.related.link}
109 - */
110 -```
142 +### Python
143
112 -### Function Documentation
113 -
114 -Every user-facing function must include:
115 -
116 -1. TSDoc documentation
117 -2. Example usage
118 -3. Parameter and return type descriptions
119 -4. Error cases
120 -
121 -Example:
122 -
123 -````typescript
124 -/**
125 - * Executes a tool with the given parameters.
126 - *
127 - * @description
128 - * This function executes a tool with the provided parameters and returns the result.
129 - * It handles authentication, parameter validation, and error cases automatically.
130 - *
131 - * @example
132 - * ```typescript
133 - * const result = await executeTool('GMAIL_SEND_EMAIL', {
134 - * userId: 'user123',
135 - * arguments: {
136 - * to: 'recipient@example.com',
137 - * subject: 'Hello',
138 - * body: 'Message content'
139 - * }
140 - * });
141 - * ```
142 - *
143 - * @param {string} toolId - The unique identifier of the tool to execute
144 - * @param {ExecuteToolOptions} options - Tool execution options
145 - * @returns {Promise<ExecuteToolResult>} The result of the tool execution
146 - *
147 - * @throws {ToolNotFoundError} When the specified tool doesn't exist
148 - * @throws {ValidationError} When required parameters are missing
149 - * @throws {AuthenticationError} When authentication fails
150 - *
151 - * @see {@link https://docs.composio.dev/api/tools#execute}
152 - */
153 -export async function executeTool(
154 - toolId: string,
155 - options: ExecuteToolOptions
156 -): Promise<ExecuteToolResult> {
157 - // Implementation
158 -}
159 -````
160 -
161 -### Code Style
162 -
163 -1. Use TypeScript for all new code
164 -2. Follow the existing code style in the repository
165 -3. Use ESLint and Prettier for code formatting
166 -4. Use meaningful variable and function names
167 -5. Keep functions small and focused
168 -6. Write unit tests for all new code
169 -7. Use async/await instead of Promises
170 -8. Use named exports instead of default exports
171 -9. Use const assertions for constants
172 -10. Use type assertions sparingly
144 +1. Follow the existing Python SDK layout under `python/`.
145 +2. Use Ruff formatting and linting through the Python make targets.
146 +3. Keep provider-specific changes inside the relevant `python/providers/*` package.
147 +4. Add pytest coverage for behavior changes.
148
149 ### Error Handling
150
176 -1. Use custom error classes
177 -2. Include meaningful error messages
178 -3. Document error cases in TSDoc
179 -4. Include error codes for API errors
180 -5. Log errors appropriately
181 -
182 -Example:
183 -
184 -```typescript
185 -/**
186 - * Custom error for tool execution failures.
187 - */
188 -export class ToolExecutionError extends ComposioError {
189 - constructor(
190 - message: string,
191 - public readonly toolId: string,
192 - public readonly cause?: Error
193 - ) {
194 - super(message, 'TOOL_EXECUTION_ERROR');
195 - this.name = 'ToolExecutionError';
196 - }
197 -}
198 -```
151 +1. Use the existing error classes and result shapes in the package you are editing.
152 +2. Include enough context in error messages to identify the failing operation.
153 +3. Avoid swallowing errors unless the caller has an explicit fallback path.
154
155 ## Documentation Requirements
156
202 -### Package Documentation
203 -
204 -Each package must include:
205 -
206 -1. README.md with:
157 +Update docs when a change affects public behavior, install flows, examples, environment variables, release steps, or provider usage.
158
208 - - Package description
209 - - Installation instructions
210 - - Usage examples
211 - - API reference
212 - - Environment variables
213 - - Contributing guidelines
159 +For documentation-site work, read [`docs/CLAUDE.md`](docs/CLAUDE.md) first. It documents the docs app, MDX conventions, link checking, generated data, and docs branch workflow.
160
215 -2. API documentation:
161 +Package documentation should generally include:
162
217 - - TSDoc for all public APIs
218 - - Example code snippets
219 - - Error handling documentation
220 - - Type definitions
221 -
222 -3. Example implementations:
223 - - Basic usage example
224 - - Advanced usage examples
225 - - Integration examples
226 -
227 -### Provider Documentation
228 -
229 -Provider packages must additionally include:
230 -
231 -1. Provider-specific setup instructions
232 -2. Authentication requirements
233 -3. Supported features
234 -4. Limitations and constraints
235 -5. Integration examples
236 -6. Streaming support details
237 -7. Error handling examples
163 +1. A short package description.
164 +2. Installation instructions.
165 +3. Usage examples.
166 +4. Public API notes.
167 +5. Environment variables or authentication requirements when relevant.
168 +6. Provider limitations or streaming details when relevant.
169
170 ## Pull Request Process
171
241 -1. Create a new branch for your changes:
172 +1. Create a branch from the target base branch. Most active SDK and docs work targets `next`.
173
174 ```bash
175 + git checkout next
176 + git pull origin next
177 git checkout -b feature/your-feature-name
178 ```
179
247 -2. Make your changes following the coding standards
180 +2. Make focused changes that match the issue or feature scope.
181
249 -3. Add tests for new functionality
182 +3. Add or update tests for behavior changes.
183
251 -4. Update documentation as needed
184 +4. Update documentation when user-facing behavior changes.
185
253 -5. Create a changeset:
186 +5. Add a changeset for changes that affect published TypeScript packages:
187
188 ```bash
189 pnpm changeset
190 ```
191
259 -6. Push your changes and create a pull request
192 + Root-level documentation-only changes, such as edits to this file, do not need a changeset.
193 +
194 +6. Run the smallest meaningful verification command locally before opening the PR.
195
261 -7. Wait for review and address any feedback
196 +7. Push your branch and open a PR against the correct base branch.
197
198 ## Creating New Providers
199
265 -1. Use the provider creation script:
200 +### TypeScript Providers
201
267 - ```bash
268 - pnpm create:provider my-provider [--agentic]
269 - ```
202 +Use the TypeScript provider creation script:
203 +
204 +```bash
205 +pnpm create:provider my-provider [--agentic]
206 +```
207
271 -2. Implement required methods:
208 +Then:
209
273 - - For non-agentic providers: `wrapTool` and `wrapTools`, and helper functions
274 - - For agentic providers: `wrapTool`, `wrapTools`, and execution handlers
210 +1. Implement the required provider methods.
211 +2. Add tests under the provider package.
212 +3. Add examples or docs when the provider has user-facing setup details.
213 +4. Run the package tests and relevant build checks.
214 +
215 +### Python Providers
216 +
217 +Use the Python provider creation target from the `python/` directory:
218 +
219 +```bash
220 +cd python
221 +make create-provider name=my-provider
222 +```
223
276 -3. Add comprehensive tests
224 +For agentic providers:
225
278 -4. Add provider documentation
226 +```bash
227 +cd python
228 +make create-provider name=my-provider agentic=true
229 +```
230
280 -5. Create example implementations
231 +Then add provider tests and run the relevant Python checks.
232
233 ## Testing Guidelines
234
284 -1. Write unit tests for all new code
285 -2. Include integration tests for providers
286 -3. Test error cases
287 -4. Test edge cases
288 -5. Use mocks appropriately
289 -6. Test streaming functionality
290 -7. Test with different Node.js versions
291 -
292 -Example test:
293 -
294 -```typescript
295 -describe('ToolExecution', () => {
296 - it('should execute a tool successfully', async () => {
297 - const result = await executeTool('TEST_TOOL', {
298 - userId: 'user123',
299 - arguments: { test: true },
300 - });
301 - expect(result.successful).toBe(true);
302 - });
303 -
304 - it('should handle errors appropriately', async () => {
305 - await expect(
306 - executeTool('INVALID_TOOL', {
307 - userId: 'user123',
308 - arguments: {},
309 - })
310 - ).rejects.toThrow(ToolNotFoundError);
311 - });
312 -});
235 +### TypeScript SDK
236 +
237 +Run the root TypeScript test suite:
238 +
239 +```bash
240 +pnpm test
241 ```
242
315 -## Release Process
243 +Run all TypeScript end-to-end tests:
244
317 -1. Create a release branch:
245 +```bash
246 +pnpm test:e2e
247 +```
248
319 - ```bash
320 - git checkout -b release/v1.2.3
321 - ```
249 +Run runtime-specific end-to-end tests:
250
323 -2. Update version numbers:
251 +```bash
252 +pnpm test:e2e:node
253 +pnpm test:e2e:deno
254 +pnpm test:e2e:cli
255 +pnpm test:e2e:cloudflare
256 +```
257
325 - ```bash
326 - pnpm changeset version
327 - ```
258 +Open the Vitest UI:
259
329 -3. Update CHANGELOG.md
260 +```bash
261 +pnpm test:ui
262 +```
263
331 -4. Create a release commit:
264 +### Python SDK
265
333 - ```bash
334 - git commit -am "Release v1.2.3"
335 - ```
266 +Set up the Python development environment:
267
337 -5. Create a pull request for the release
268 +```bash
269 +cd python
270 +make env
271 +source .venv/bin/activate
272 +```
273
339 -6. After approval, merge and tag:
274 +Run Python checks:
275
341 - ```bash
342 - git tag v1.2.3
343 - git push origin v1.2.3
344 - ```
276 +```bash
277 +make fmt
278 +make chk
279 +make tst
280 +make snt
281 +```
282
346 -7. Publish to npm:
347 - ```bash
348 - pnpm changeset publish
349 - ```
283 +You can also run a focused pytest command through uv:
284 +
285 +```bash
286 +uv run pytest tests/test_sdk.py -v
287 +```
288 +
289 +### Docs Site
290 +
291 +For docs changes:
292 +
293 +```bash
294 +cd docs
295 +bun install
296 +bun run build
297 +bun run lint:links
298 +```
299 +
300 +See [`docs/CLAUDE.md`](docs/CLAUDE.md) for the full docs workflow.
301 +
302 +## Release Process
303 +
304 +Only maintainers publish releases.
305 +
306 +For TypeScript package and CLI release details, use [`ts/docs/internal/release.md`](ts/docs/internal/release.md). The root scripts are:
307 +
308 +```bash
309 +pnpm changeset
310 +pnpm changeset:version
311 +pnpm changeset:release
312 +```
313 +
314 +For Python package release details, use [`python/docs/release.md`](python/docs/release.md). Python package versioning and release preparation are handled from the `python/` workspace.
315
316 ## Questions and Support
317