How to Report a Bug in Corsair: A Step-by-Step Guide for Contributors

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 and the .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) and enforced through GitHub's issue templates.

---

Step 1: Open a New Issue on GitHub

Navigate to the Corsair repository 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 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) 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), 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 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:

**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	Central guide for the bug-report workflow, branching model, and contribution standards
.github/ISSUE_TEMPLATE/bug_report.yml	Pre-populated issue form that enforces required fields
.github/labeler.yml	Auto-applies the bug label to issues from the bug-report template
packages/slack/README.md	Plugin-specific documentation for Slack-related bugs
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 (line 99)
• Automation — GitHub Actions in .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 system handles labels; focus on content quality
• Reference key files — Use 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 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 file contains setup instructions for the local testing environment. Run cd demo/testing && pnpm test after following the quickstart in CONTRIBUTING.md to replicate most reported issues locally.

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