Skip to content

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

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

Alberto Schiabelf254d1333a1c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0e7e6f1f0..e1cf0717b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,25 +1,40 @@
# Contributing to Composio SDK
-Thank you for your interest in contributing to Composio SDK! This document provides guidelines and instructions for contributing to the project.
+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.
## Table of Contents
- [Development Setup](#development-setup)
- [Project Structure](#project-structure)
+- [Development Commands](#development-commands)
- [Coding Standards](#coding-standards)
- [Documentation Requirements](#documentation-requirements)
- [Pull Request Process](#pull-request-process)
- [Creating New Providers](#creating-new-providers)
- [Testing Guidelines](#testing-guidelines)
- [Release Process](#release-process)
+- [Questions and Support](#questions-and-support)
## Development Setup
### Prerequisites
-- Node.js (Latest LTS version recommended)
-- [pnpm](https://pnpm.io/) (v10.8.0 or later)
-- [bun](https://bun.sh) for productivity (optional)
+Tool versions are pinned in [`mise.toml`](mise.toml), which is the source of truth for local development and CI:
+
+- Node.js 24.17.0
+- pnpm 11.8.0
+- Bun 1.3.10
+- Deno 2.6.7
+- Python 3.12
+- uv 0.8.19
+
+Use [mise](https://mise.jdx.dev) to install the toolchain:
+
+```bash
+mise install
+```
+
+pnpm is installed through mise's npm backend. Do not rely on Corepack for this repository.
### Getting Started
@@ -30,39 +45,79 @@ Thank you for your interest in contributing to Composio SDK! This document provi
cd composio
```
-2. Install dependencies:
+2. Install the pinned toolchain:
+
+ ```bash
+ mise install
+ ```
+
+3. Install dependencies:
```bash
pnpm install
```
-3. Build the project:
+4. Build the project:
```bash
pnpm build
```
-4. Run tests:
+5. Run tests:
+
```bash
pnpm test
```
-### Development Commands
+## Project Structure
+
+```text
+composio/
+├── ts/ # TypeScript SDK workspace
+│ ├── packages/
+│ │ ├── core/ # Core SDK package (@composio/core)
+│ │ ├── cli/ # CLI binary and command implementations
+│ │ ├── cli-keyring/ # Keyring helper for the CLI
+│ │ ├── cli-local-tools/ # Local tools support for the CLI
+│ │ ├── providers/ # AI framework provider adapters
+│ │ ├── json-schema-to-zod/ # Schema conversion utility
+│ │ └── ts-builders/ # TypeScript build helpers
+│ ├── e2e-tests/ # Runtime and CLI end-to-end tests
+│ ├── examples/ # TypeScript examples
+│ └── scripts/ # TypeScript build and maintenance scripts
+├── python/ # Python SDK
+│ ├── composio/ # Main Python package
+│ ├── providers/ # Python provider adapters
+│ ├── tests/ # pytest test suite
+│ ├── scripts/ # Python development and release scripts
+│ └── docs/ # Python release notes and process docs
+├── docs/ # Documentation site
+├── test/ # Root-level release/install script tests
+└── .github/ # GitHub Actions and shared CI actions
+```
+
+## Development Commands
```bash
-# Lint code
+# Build all packages
+pnpm build
+
+# Build TypeScript packages only
+pnpm build:packages
+
+# Lint TypeScript packages
pnpm lint
-# Fix linting issues
+# Fix lint issues where possible
pnpm lint:fix
-# Format code
+# Format supported files
pnpm format
-# Create a new provider
+# Create a new TypeScript provider
pnpm create:provider <provider-name> [--agentic]
-# Create a new example
+# Create a new TypeScript example
pnpm create:example <example-name>
# Check peer dependencies
@@ -72,281 +127,191 @@ pnpm check:peer-deps
pnpm update:peer-deps
```
-## Project Structure
+## Coding Standards
-```
-composio/
-├── packages/ # Main packages directory
-│ ├── core/ # Core SDK package
-│ └── providers/ # Provider implementations
-├── examples/ # Example implementations
-├── docs/ # Documentation
-├── scripts/ # Development and build scripts
-└── .github/ # GitHub configuration
-```
+### TypeScript
-## Coding Standards
+1. Follow the style of the package you are editing.
+2. Use TypeScript for new TypeScript SDK code.
+3. Use named exports for public APIs unless the local package pattern says otherwise.
+4. Keep public API changes typed and documented with TSDoc.
+5. Add focused tests for new behavior and bug fixes.
+6. Use ESLint and Prettier through the repo scripts.
+7. Keep generated or vendored code out of manual edits unless the package explicitly owns that output.
-### File Headers
-
-Every source file must include a header comment with:
-
-```typescript
-/**
- * @file Description of what this file does/contains
- * @module path/to/module
- * @description Detailed description of the file's purpose
- *
- * @author Original Author <[email protected]>
- * @contributors
- * - Contributor Name <[email protected]>
- *
- * @copyright Composio 2024
- * @license ISC
- *
- * @see {@link https://related.documentation.link}
- * @see {@link https://another.related.link}
- */
-```
+### Python
-### Function Documentation
-
-Every user-facing function must include:
-
-1. TSDoc documentation
-2. Example usage
-3. Parameter and return type descriptions
-4. Error cases
-
-Example:
-
-````typescript
-/**
- * Executes a tool with the given parameters.
- *
- * @description
- * This function executes a tool with the provided parameters and returns the result.
- * It handles authentication, parameter validation, and error cases automatically.
- *
- * @example
- * ```typescript
- * const result = await executeTool('GMAIL_SEND_EMAIL', {
- * userId: 'user123',
- * arguments: {
- * subject: 'Hello',
- * body: 'Message content'
- * }
- * });
- * ```
- *
- * @param {string} toolId - The unique identifier of the tool to execute
- * @param {ExecuteToolOptions} options - Tool execution options
- * @returns {Promise<ExecuteToolResult>} The result of the tool execution
- *
- * @throws {ToolNotFoundError} When the specified tool doesn't exist
- * @throws {ValidationError} When required parameters are missing
- * @throws {AuthenticationError} When authentication fails
- *
- * @see {@link https://docs.composio.dev/api/tools#execute}
- */
-export async function executeTool(
- toolId: string,
- options: ExecuteToolOptions
-): Promise<ExecuteToolResult> {
- // Implementation
-}
-````
-
-### Code Style
-
-1. Use TypeScript for all new code
-2. Follow the existing code style in the repository
-3. Use ESLint and Prettier for code formatting
-4. Use meaningful variable and function names
-5. Keep functions small and focused
-6. Write unit tests for all new code
-7. Use async/await instead of Promises
-8. Use named exports instead of default exports
-9. Use const assertions for constants
-10. Use type assertions sparingly
+1. Follow the existing Python SDK layout under `python/`.
+2. Use Ruff formatting and linting through the Python make targets.
+3. Keep provider-specific changes inside the relevant `python/providers/*` package.
+4. Add pytest coverage for behavior changes.
### Error Handling
-1. Use custom error classes
-2. Include meaningful error messages
-3. Document error cases in TSDoc
-4. Include error codes for API errors
-5. Log errors appropriately
-
-Example:
-
-```typescript
-/**
- * Custom error for tool execution failures.
- */
-export class ToolExecutionError extends ComposioError {
- constructor(
- message: string,
- public readonly toolId: string,
- public readonly cause?: Error
- ) {
- super(message, 'TOOL_EXECUTION_ERROR');
- this.name = 'ToolExecutionError';
- }
-}
-```
+1. Use the existing error classes and result shapes in the package you are editing.
+2. Include enough context in error messages to identify the failing operation.
+3. Avoid swallowing errors unless the caller has an explicit fallback path.
## Documentation Requirements
-### Package Documentation
-
-Each package must include:
-
-1. README.md with:
+Update docs when a change affects public behavior, install flows, examples, environment variables, release steps, or provider usage.
- - Package description
- - Installation instructions
- - Usage examples
- - API reference
- - Environment variables
- - Contributing guidelines
+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.
-2. API documentation:
+Package documentation should generally include:
- - TSDoc for all public APIs
- - Example code snippets
- - Error handling documentation
- - Type definitions
-
-3. Example implementations:
- - Basic usage example
- - Advanced usage examples
- - Integration examples
-
-### Provider Documentation
-
-Provider packages must additionally include:
-
-1. Provider-specific setup instructions
-2. Authentication requirements
-3. Supported features
-4. Limitations and constraints
-5. Integration examples
-6. Streaming support details
-7. Error handling examples
+1. A short package description.
+2. Installation instructions.
+3. Usage examples.
+4. Public API notes.
+5. Environment variables or authentication requirements when relevant.
+6. Provider limitations or streaming details when relevant.
## Pull Request Process
-1. Create a new branch for your changes:
+1. Create a branch from the target base branch. Most active SDK and docs work targets `next`.
```bash
+ git checkout next
+ git pull origin next
git checkout -b feature/your-feature-name
```
-2. Make your changes following the coding standards
+2. Make focused changes that match the issue or feature scope.
-3. Add tests for new functionality
+3. Add or update tests for behavior changes.
-4. Update documentation as needed
+4. Update documentation when user-facing behavior changes.
-5. Create a changeset:
+5. Add a changeset for changes that affect published TypeScript packages:
```bash
pnpm changeset
```
-6. Push your changes and create a pull request
+ Root-level documentation-only changes, such as edits to this file, do not need a changeset.
+
+6. Run the smallest meaningful verification command locally before opening the PR.
-7. Wait for review and address any feedback
+7. Push your branch and open a PR against the correct base branch.
## Creating New Providers
-1. Use the provider creation script:
+### TypeScript Providers
- ```bash
- pnpm create:provider my-provider [--agentic]
- ```
+Use the TypeScript provider creation script:
+
+```bash
+pnpm create:provider my-provider [--agentic]
+```
-2. Implement required methods:
+Then:
- - For non-agentic providers: `wrapTool` and `wrapTools`, and helper functions
- - For agentic providers: `wrapTool`, `wrapTools`, and execution handlers
+1. Implement the required provider methods.
+2. Add tests under the provider package.
+3. Add examples or docs when the provider has user-facing setup details.
+4. Run the package tests and relevant build checks.
+
+### Python Providers
+
+Use the Python provider creation target from the `python/` directory:
+
+```bash
+cd python
+make create-provider name=my-provider
+```
-3. Add comprehensive tests
+For agentic providers:
-4. Add provider documentation
+```bash
+cd python
+make create-provider name=my-provider agentic=true
+```
-5. Create example implementations
+Then add provider tests and run the relevant Python checks.
## Testing Guidelines
-1. Write unit tests for all new code
-2. Include integration tests for providers
-3. Test error cases
-4. Test edge cases
-5. Use mocks appropriately
-6. Test streaming functionality
-7. Test with different Node.js versions
-
-Example test:
-
-```typescript
-describe('ToolExecution', () => {
- it('should execute a tool successfully', async () => {
- const result = await executeTool('TEST_TOOL', {
- userId: 'user123',
- arguments: { test: true },
- });
- expect(result.successful).toBe(true);
- });
-
- it('should handle errors appropriately', async () => {
- await expect(
- executeTool('INVALID_TOOL', {
- userId: 'user123',
- arguments: {},
- })
- ).rejects.toThrow(ToolNotFoundError);
- });
-});
+### TypeScript SDK
+
+Run the root TypeScript test suite:
+
+```bash
+pnpm test
```
-## Release Process
+Run all TypeScript end-to-end tests:
-1. Create a release branch:
+```bash
+pnpm test:e2e
+```
- ```bash
- git checkout -b release/v1.2.3
- ```
+Run runtime-specific end-to-end tests:
-2. Update version numbers:
+```bash
+pnpm test:e2e:node
+pnpm test:e2e:deno
+pnpm test:e2e:cli
+pnpm test:e2e:cloudflare
+```
- ```bash
- pnpm changeset version
- ```
+Open the Vitest UI:
-3. Update CHANGELOG.md
+```bash
+pnpm test:ui
+```
-4. Create a release commit:
+### Python SDK
- ```bash
- git commit -am "Release v1.2.3"
- ```
+Set up the Python development environment:
-5. Create a pull request for the release
+```bash
+cd python
+make env
+source .venv/bin/activate
+```
-6. After approval, merge and tag:
+Run Python checks:
- ```bash
- git tag v1.2.3
- git push origin v1.2.3
- ```
+```bash
+make fmt
+make chk
+make tst
+make snt
+```
-7. Publish to npm:
- ```bash
- pnpm changeset publish
- ```
+You can also run a focused pytest command through uv:
+
+```bash
+uv run pytest tests/test_sdk.py -v
+```
+
+### Docs Site
+
+For docs changes:
+
+```bash
+cd docs
+bun install
+bun run build
+bun run lint:links
+```
+
+See [`docs/CLAUDE.md`](docs/CLAUDE.md) for the full docs workflow.
+
+## Release Process
+
+Only maintainers publish releases.
+
+For TypeScript package and CLI release details, use [`ts/docs/internal/release.md`](ts/docs/internal/release.md). The root scripts are:
+
+```bash
+pnpm changeset
+pnpm changeset:version
+pnpm changeset:release
+```
+
+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.
## Questions and Support