# How to Contribute to Corsair: The Official Contribution Guidelines Explained

> Learn how to contribute to Corsair. Follow our official guidelines: create an issue, claim integrations, fork, use dedicated branches, Conventional Commits, and test plugins before submitting a PR.

- Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Contributors must create an issue first, claim integrations via the OSS portal, fork fresh, work on dedicated branches, use Conventional Commits, and test plugins in the `demo/testing` sandbox before opening a PR.**

Corsair is a TypeScript-based monorepo that combines a core integration framework with dozens of plugin packages. Understanding the **Corsair contribution guideline** ensures your work aligns with the project's stability, type-safety, and plugin ecosystem requirements. This guide breaks down the complete workflow as documented in the official [[`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md)](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md).

## Before You Start: Issue Creation and Integration Claims

Every contribution begins with coordination. The **Corsair contribution guideline** requires two upfront steps to prevent duplicate work and surface design constraints early.

### Create an Issue First

Open a new issue using one of three templates:
- `bug_report` — for defect fixes
- `feature_request` — for enhancements to core or existing plugins
- `integration_request` — for new plugin proposals

This guarantees your work is visible and aligned with maintainers before you invest development time.

### Claim Your Integration

For new plugins, visit [corsair.dev/oss](https://corsair.dev/oss) and claim the integration you intend to build. This prevents multiple contributors from building competing implementations of the same service.

## Fork and Local Setup

Fresh forks eliminate hidden merge conflicts. Clone into a new directory rather than reusing old forks:

```bash

# Fork first: https://github.com/corsairdev/corsair/fork

git clone https://github.com/<your-username>/corsair.git corsair-your-plugin
cd corsair-your-plugin
pnpm install

```

## Branch Workflow and Commit Standards

### Dedicated Branches

Create focused branches using the pattern `<type>/<short-description>`:

```bash
git checkout -b feat/slack-message-typing

```

Keep each branch limited to a single logical change. This isolates work and simplifies review.

### Conventional Commits

The **Corsair contribution guideline** enforces the **Conventional Commits** specification for automated changelog generation:

```bash
git commit -m "feat(slack): add message-typing events"
git commit -m "fix(core): handle null webhook payloads"
git commit -m "docs(readme): update installation steps"

```

Common prefixes include `fix(scope):`, `feat(scope):`, and `docs:`.

## Understanding the Monorepo Structure

Code changes must land in the correct package. The repository organizes into three logical groups:

| Group | Location | Purpose |
|-------|----------|---------|
| **Core framework** | `packages/corsair/` | Runtime, shared types, and utilities |
| **Plugin packages** | `packages/*` (e.g., `packages/slack/`) | Individual service integrations |
| **Feature packages** | `packages/cli/`, `packages/ui/`, `packages/studio/`, etc. | CLI tools, UI helpers, and local studio |

Respecting these boundaries maintains the dependency graph and prevents circular imports.

## Testing Workflow for Plugins

The `demo/testing` sandbox provides the canonical environment for plugin validation. This ensures your plugin runs in the exact setup the core team uses.

### Register Your Plugin

Edit [`demo/testing/src/server/corsair.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/server/corsair.ts):

```typescript
import { SlackPlugin } from '@corsair-dev/slack';

export const plugins = [SlackPlugin];

```

### Write Test Scripts

Create usage scripts in [`demo/testing/src/scripts/test-script.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/scripts/test-script.ts):

```typescript
import { corsair } from '../server/corsair';

await corsair.plugins.slack.sendMessage({ channel: 'C12345', text: 'Hello' });

```

### Execute Tests

```bash
cd demo/testing
pnpm test

```

## Building New Plugins

### Generate the Scaffold

Use the official generator to create a consistent starting point:

```bash
pnpm run generate:plugin <PluginName>

```

This creates the package structure, registers the plugin, and provides endpoint, auth, schema, and webhook handling templates.

### Authentication Design

Select the appropriate auth model for your target service:
- **OAuth 2.0** — for user-authorized integrations
- **API key** — for service-to-service authentication
- **Webhook signature validation** — for incoming event security

Implement token refresh logic and signature verification as required by the provider.

### Webhook Testing

Use a tunnel service like **ngrok** to test webhook flows locally:

```bash
ngrok http 3000

```

Register the forwarding URL with your service provider and verify payload handling end-to-end.

## Code Quality Requirements

### Backwards Compatibility

Before modifying core APIs in `packages/corsair/`, assess impact on existing plugins and downstream packages. Breaking changes require:
- Coordination across all affected packages
- Clear risk documentation in the PR description
- Migration guidance for downstream users

### Type Safety

The **Corsair contribution guideline** prohibits `as any` and broad type assertions. Prefer:
- Refining existing interfaces
- Adding new type definitions
- Narrowing through type guards

If an assertion is unavoidable, include a concise comment explaining the necessity.

## Submitting Your Pull Request

Link your issue, describe API changes, explain testing steps, and flag design decisions. The PR checklist in [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) requires:
- Issue reference for non-trivial changes
- Description of surface area added or modified
- Verification that `demo/testing` passes

Small documentation fixes may proceed without issue context; larger changes must have prior issue approval.

## Key Files Reference

| File | Role |
|------|------|
| [[`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md)](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) | Complete contribution workflow |
| [`packages/corsair/`](https://github.com/corsairdev/corsair/tree/main/packages/corsair) | Core framework and shared types |
| [`packages/*/`](https://github.com/corsairdev/corsair/tree/main/packages) | Individual plugin implementations |
| [`demo/testing/`](https://github.com/corsairdev/corsair/tree/main/demo/testing) | Local sandbox for plugin development |
| [`scripts/pr-review/`](https://github.com/corsairdev/corsair/tree/main/scripts/pr-review) | Automated PR enforcement tooling |

## Summary

- **Create an issue first** using the appropriate template before any development work
- **Claim integrations** at corsair.dev/oss to prevent duplicate plugin efforts
- **Fork freshly** and install dependencies with `pnpm install`
- **Use dedicated branches** with Conventional Commits for clean history
- **Respect package boundaries**: core in `packages/corsair/`, plugins in `packages/*/`
- **Test in `demo/testing/`**: register plugins, write scripts, run `pnpm test`
- **Generate plugins** with `pnpm run generate:plugin <Name>` for consistent scaffolds
- **Design auth and webhooks carefully**, testing with ngrok when needed
- **Preserve backwards compatibility** and coordinate breaking changes
- **Maintain type safety** without `as any` assertions

## Frequently Asked Questions

### Do I need to open an issue before every contribution?

Yes, with one exception. The **Corsair contribution guideline** requires issue creation for bug fixes, features, and new plugins. Only trivial documentation fixes may proceed without prior issue context. This coordination prevents wasted effort and surfaces design constraints early.

### How do I prevent someone else from building the same plugin?

Claim your integration on the public OSS portal at [corsair.dev/oss](https://corsair.dev/oss). This reservation system prevents duplicate plugin development and keeps the ecosystem organized. The claim is verified when you reference it in your issue and PR.

### What testing is required for new plugins?

All plugins must run successfully in the `demo/testing` sandbox. Register your plugin in [`demo/testing/src/server/corsair.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/server/corsair.ts), write usage scripts in [`demo/testing/src/scripts/test-script.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/scripts/test-script.ts), and execute `pnpm test` from the `demo/testing` directory. This validates your plugin against the same environment the core team uses.