How to Report Bugs in Automattic/harper: GitHub Issues and Discord

Report bugs in Automattic/harper through GitHub Issues for formal tracking or via Discord for preliminary discussion, as documented in the repository's contributor guidelines.

The Harper grammar and spell-checking engine, maintained by Automattic, provides clear pathways for community members to report issues. Whether you've encountered a crash in the Rust core or a glitch in the browser extension, understanding the proper channels ensures your bug report reaches the right maintainers efficiently.

GitHub Issues: The Primary Bug Reporting Channel

The official method to report bugs in Automattic/harper is through the repository's GitHub Issue tracker. This creates a permanent record for triage, assignment, and resolution tracking.

Creating an Effective Bug Report

When filing an issue, provide a reproducible minimal example, your Harper version, and relevant environment details. The project encourages using appropriate labels such as bug, area:core, or area:extension to route issues correctly.

Use the GitHub CLI to create a structured bug report from your terminal:

gh issue create \
  --title "Spelling lint fails on user-defined dictionary words" \
  --body "### Description

A spelling lint incorrectly flags the word **“harperjs”** even after adding it to the mutable dictionary.

### Steps to Reproduce

1. Run `harper-cli lint` on a file containing “harperjs”.
2. Observe the lint warning.

### Environment

- harper-js version: 2.4.1
- OS: macOS 13.5
- Rust toolchain: stable

### Expected Behaviour

The word should be recognized as valid when present in the mutable dictionary." \
  --label bug,area:core

Alternatively, submit programmatically via the GitHub REST API:

curl -X POST \
  -H "Authorization: token <TOKEN>" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/Automattic/harper/issues \
  -d '{"title":"Harper-Desktop highlighter mis-aligns on secondary monitor","body":"When I move the highlighter window to a secondary monitor the overlay coordinates are off by ~10 px. Steps to reproduce: 1) Open Harper-Desktop, 2) Enable highlighter, 3) Drag window to secondary monitor. Expected: overlay aligns with text. Actual: offset.","labels":["bug","area:desktop"]}'

Discord: Preliminary Discussion and Quick Questions

For non-critical problems or when you need early feedback before filing a formal issue, Harper maintains a public Discord community. This channel is ideal for clarifying whether unexpected behavior constitutes a bug or requesting guidance on reproduction steps.

According to packages/web/src/routes/docs/contributors/introduction/+page.md, the Discord server serves as a collaborative space where contributors can discuss potential issues with the core team before committing to a formal report.

Essential Information for Bug Reports

Regardless of which channel you choose initially, effective Harper bug reports should include:

• Version information: The specific Harper release or commit hash
• Environment details: Operating system, browser version (for extensions), or Rust toolchain version (for CLI)
• Minimal reproduction steps: A concise sequence that triggers the bug consistently
• Expected vs. actual behavior: Clear description of what should happen versus what occurs
• Relevant logs: Error messages or stack traces from harper-cli or browser consoles

Where Bug Reporting is Documented

The canonical documentation for reporting bugs resides in two key locations:

• CONTRIBUTING.md: The repository root file serves as the entry point, redirecting newcomers to comprehensive contributor documentation
• packages/web/src/routes/docs/contributors/introduction/+page.md: This file explicitly outlines the dual-channel approach (GitHub Issues and Discord) for submitting bug reports and feature requests

If issue templates exist in .github/ISSUE_TEMPLATE/, they provide structured forms ensuring you include necessary diagnostic information automatically.

Summary

• GitHub Issues provide the formal, tracked method to report bugs in Automattic/harper, suitable for verified defects requiring code changes
• Discord offers a conversational preliminary channel for clarifying issues or discussing non-critical bugs before formal filing
• Documentation in packages/web/src/routes/docs/contributors/introduction/+page.md and CONTRIBUTING.md governs the official reporting workflow
• Include version numbers, reproduction steps, and environment details in every formal bug report to expedite triage

Frequently Asked Questions

Where do I report bugs in Automattic/harper?

Report bugs through the GitHub Issue tracker at github.com/Automattic/harper/issues for permanent tracking and resolution. For quick questions or preliminary validation, use the community Discord server linked in the contributor documentation.

What information should I include in a Harper bug report?

Include the Harper version (e.g., harper-js 2.4.1 or commit hash), your operating system and toolchain details, minimal reproduction steps, expected versus actual behavior, and any relevant error logs. The packages/web/src/routes/docs/contributors/introduction/+page.md file emphasizes these details for efficient triage.

Can I discuss bugs on Discord before opening a GitHub issue?

Yes. The Automattic/harper documentation explicitly encourages using Discord for quick clarification and early feedback. If the discussion confirms a genuine bug, you should subsequently open a formal GitHub Issue to ensure proper tracking and assignment.

Is there a specific template for Harper bug reports?

The repository may provide issue templates in .github/ISSUE_TEMPLATE/ that automatically prompt for required information. If templates are not available, follow the structure documented in the contributor guidelines: include a clear title, description, reproduction steps, environment details, and appropriate labels like bug or area:core.

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