Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: update contributing guide for current repo (#3651)
Alberto Schiabelf254d1333a1c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 provicd composio```-2. Install dependencies:+2. Install the pinned toolchain:++ ```bash+ mise install+ ```++3. Install dependencies:```bashpnpm install```-3. Build the project:+4. Build the project:```bashpnpm build```-4. Run tests:+5. Run tests:+```bashpnpm 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 packagespnpm lint-# Fix linting issues+# Fix lint issues where possiblepnpm lint:fix-# Format code+# Format supported filespnpm format-# Create a new provider+# Create a new TypeScript providerpnpm create:provider <provider-name> [--agentic]-# Create a new example+# Create a new TypeScript examplepnpm create:example <example-name># Check peer dependencies@@ -72,281 +127,191 @@ pnpm check:peer-depspnpm 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: {- * to: '[email protected]',- * 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 nextgit 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:```bashpnpm 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