How to Contribute to Corsair: The Official Contribution Guidelines Explained

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).

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 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:

# 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>:

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:

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:

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

export const plugins = [SlackPlugin];

Write Test Scripts

Create usage scripts in demo/testing/src/scripts/test-script.ts:

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

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

Execute Tests

cd demo/testing
pnpm test

Building New Plugins

Generate the Scaffold

Use the official generator to create a consistent starting point:

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:

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 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)	Complete contribution workflow
packages/corsair/	Core framework and shared types
packages/*/	Individual plugin implementations
demo/testing/	Local sandbox for plugin development
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. 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, write usage scripts in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}