# How to Report a Bug in Corsair: A Step-by-Step Guide for Contributors > Learn how to report a bug in Corsair by opening an issue with our Bug Report template. Follow our step-by-step guide for detailed reproduction steps and environment information. - Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair) - Tags: how-to-guide - Published: 2026-09-01 --- **To report a bug in Corsair, open a new issue using the Bug Report template, complete all required fields including reproduction steps and environment details, and submit—GitHub automation will handle labeling and triage.** The Corsair monorepo uses a structured bug-reporting workflow designed to keep issues actionable and routable to the right maintainers. Whether you've hit a glitch in the Slack plugin or a core framework issue, following the official process in [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) and the [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/corsairdev/corsair/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) template ensures your report gets attention fast. --- ## The Corsair Bug Report Workflow Corsair's maintainers require all bug reports to follow a specific path from discovery to submission. This workflow is documented in [[`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md)](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) and enforced through GitHub's issue templates. --- ## Step 1: Open a New Issue on GitHub Navigate to the [Corsair repository](https://github.com/corsairdev/corsair) and click **New issue**. The repository provides multiple templates, but for bugs you must select **Bug report**. This is referenced explicitly at line 17 of [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) as the entry point for all bug-related communication. --- ## Step 2: Use the Bug Report Template The **Bug report** template (defined in [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/corsairdev/corsair/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml)) pre-populates a checklist that forces complete information. Do not delete sections or use a blank issue—partial reports are typically closed with a request to resubmit. --- ## Step 3: Complete All Required Fields The template enforces eight specific fields. Provide accurate, detailed content for each: | Field | What to Include | |-------|-----------------| | **Title** | Concise, specific summary (e.g., `Slack plugin: message typing indicator fails on reconnect`) | | **Description** | Brief narrative explaining the problem and its impact | | **Steps to Reproduce** | Numbered list of exact actions that trigger the bug | | **Expected Behaviour** | What should have happened | | **Actual Behaviour** | What happened instead, with error messages or logs | | **Environment** | OS, Node version (Node 22+ required per [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md)), pnpm version, and relevant plugin names | | **Screenshots / Logs** | Console output, stack traces, or visual evidence | | **Additional Context** | Related PRs, discussions, or configuration files | --- ## Step 4: Automatic Labeling and Triage Once submitted, the repository's GitHub automation takes over. The [`.github/labeler.yml`](https://github.com/corsairdev/corsair/blob/main/.github/labeler.yml) configuration automatically applies the **bug** label based on template selection, routing the issue to the maintainers' triage board. No manual labeling is required. --- ## Example Bug Report Template Copy-paste this structure into the GitHub form after selecting **Bug report**: ```markdown **Title** `Slack plugin: message typing indicator fails on reconnect` **Description** When the Slack integration loses its WebSocket connection and then reconnects, the typing indicator message never clears, causing UI glitches in Corsair Studio. **Steps to Reproduce** 1. `pnpm run generate:plugin Slack` (or use an existing Slack plugin). 2. Run the demo server: `cd demo/testing && pnpm test`. 3. Send a message in Slack that triggers a typing event. 4. Simulate a network drop (e.g., disable Wi-Fi) and restore it. 5. Observe that the typing indicator stays visible. **Expected Behaviour** The typing indicator should disappear automatically once the connection is restored. **Actual Behaviour** The indicator remains on screen; console logs show `WebSocket reconnect` but no `typing.stop` event is emitted. **Environment** - OS: macOS 14.5 - Node: v22.4.0 (as required by the repo) - pnpm: 10.5.0 - Plugin: `packages/slack` **Screenshots / Logs** ``` [2026-09-01T12:34:56.789Z] debug: WebSocket reconnect [2026-09-01T12:34:57.001Z] error: typing.stop not received ``` **Additional Context** Related issue: #1234 (feature request for improved reconnection handling). ``` --- ## Key Files in the Bug Reporting Process Understanding these source files helps you navigate the Corsair codebase when investigating or reporting bugs: | File | Purpose | |------|---------| | [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) | Central guide for the bug-report workflow, branching model, and contribution standards | | [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/corsairdev/corsair/blob/main/.github/ISSUE_TEMPLATE/bug_report.yml) | Pre-populated issue form that enforces required fields | | [`.github/labeler.yml`](https://github.com/corsairdev/corsair/blob/main/.github/labeler.yml) | Auto-applies the **bug** label to issues from the bug-report template | | [`packages/slack/README.md`](https://github.com/corsairdev/corsair/blob/main/packages/slack/README.md) | Plugin-specific documentation for Slack-related bugs | | [`demo/testing/README.md`](https://github.com/corsairdev/corsair/blob/main/demo/testing/README.md) | Instructions for running the local testing sandbox | --- ## Why This Structure Matters for Corsair The Corsair monorepo contains multiple plugins (e.g., `packages/slack`, `packages/googlecloudvision`) with complex interactions. The bug report workflow addresses three critical needs: - **Reproducibility** — Deterministic steps let maintainers trigger failures consistently across environments - **Traceability** — Plugin-specific bugs get routed to the correct package owners via the package list in [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) (line 99) - **Automation** — GitHub Actions in [`.github/workflows/pr-checks.yml`](https://github.com/corsairdev/corsair/blob/main/.github/workflows/pr-checks.yml) keeps triage fast and consistent --- ## Summary - **Start with the template** — Always use the Bug report issue template for bug submissions in Corsair - **Be specific** — Include exact reproduction steps, environment details, and relevant plugin paths - **Let automation work** — The [`.github/labeler.yml`](https://github.com/corsairdev/corsair/blob/main/.github/labeler.yml) system handles labels; focus on content quality - **Reference key files** — Use [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) for process and plugin READMEs for context - **Follow Node/pnpm requirements** — Node 22+ is mandatory; state your versions explicitly --- ## Frequently Asked Questions ### What happens if I don't use the Bug report template? Issues created without the template are likely to be closed by maintainers with a request to resubmit. The template enforces information density that the triage process depends on—skipping it creates manual work for volunteers and delays resolution. ### How do I know which plugin to reference in my bug report? Check the package list in [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) around line 99. If your bug involves Slack integration, reference `packages/slack`. For Google Cloud Vision issues, use `packages/googlecloudvision`. When uncertain, describe the feature area and maintainers will re-label appropriately. ### Can I report a bug if I can't reproduce it consistently? Yes, but flag the issue as **intermittent** in the description and provide as much environmental detail as possible. Include timestamps, network conditions, and any patterns you've observed. The Corsair team may convert these to investigation issues rather than immediate fixes. ### Where do I find the testing sandbox mentioned in bug reports? The [`demo/testing/README.md`](https://github.com/corsairdev/corsair/blob/main/demo/testing/README.md) file contains setup instructions for the local testing environment. Run `cd demo/testing && pnpm test` after following the quickstart in [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) to replicate most reported issues locally.