How to Report a Bug in Macro: A Complete Guide to the Official Workflow

Report bugs in Macro by opening a GitHub issue with a clear reproduction case, using the bug(<component>): description title format, and escalating security vulnerabilities privately to security@macro.com.

The Macro project maintains structured contribution guidelines to ensure bugs are triaged and resolved efficiently. Whether you've encountered a crash in the email service or unexpected behavior in the chat component, following the established workflow in CONTRIBUTING.md helps maintainers reproduce and fix issues faster. This guide walks through the complete bug reporting process using the official Macro source code practices.

Start with a GitHub Issue

Never submit code changes without first creating an issue. The maintainers need to confirm that a problem is valid, understand its scope, and prioritize it against other work. As documented in CONTRIBUTING.md under "Start with an issue," this step prevents wasted effort on fixes that may not align with project direction.

To create an issue:

1. Navigate to the macro-inc/macro repository on GitHub
2. Click Issues → New issue
3. Select the appropriate issue template if available

Format Your Bug Report Correctly

Macro uses Conventional Commits formatting for issue titles. This standardization enables automated changelog generation and clear component identification.

Issue Title Format

bug(<component>): short description

Valid components include email, chat, or other subsystem names found in the codebase. For example:

bug(email): crash when opening Gmail attachment

Required Body Sections

Your issue description must include:

• Summary – One-paragraph overview of the bug
• Steps to Reproduce – Numbered sequence including environment, commands, and configuration
• Expected Behavior – What should happen
• Actual Behavior – What actually happens
• Environment Details – OS, Macro version, database version
• Logs or Stack Traces – Redacted of any secrets or credentials

Complete Example Issue

# Issue Body

**Summary**
The email service crashes when an attachment with a `.msg` extension is opened.

**Steps to Reproduce**
1. Open Macro and navigate to an email with a `.msg` attachment.
2. Click the attachment preview button.
3. Observe the panic in the logs.

**Expected**
Attachment preview renders the content.

**Actual**
Service panics with `unwrap()` error.

**Environment**
- OS: macOS 14.2
- Macro version: `v2.3.1`
- Docker compose DB version: PostgreSQL 15

**Logs**

thread 'main' panicked at src/services/email_service/...: panic!("Failed to parse attachment")

Apply Appropriate Labels

Labels help the triage team route issues efficiently. Apply any relevant tags from Macro's existing label set:

• bug – General bug classification
• high priority – Critical impact issues
• Component-specific labels – email, chat, or other subsystem tags

Label selection happens after issue creation through GitHub's interface.

Report Security Vulnerabilities Privately

Public GitHub issues are inappropriate for bugs that could expose data, bypass authentication, or otherwise compromise security. The README.md Security section specifies a dedicated channel for these reports.

Contact: security@macro.com

Include in your security report:

• Detailed vulnerability description
• Proof of concept or reproduction steps
• Potential impact assessment
• Suggested remediation if available

The security team will acknowledge receipt and coordinate disclosure timelines.

Engage with Maintainers

Active collaboration accelerates resolution. After submitting your issue:

• Respond promptly to clarifying questions
• Provide additional logs when requested
• Test suggested fixes or workarounds
• Update the issue with new findings

Maintainers may request environment details, specific file contents from src/services/, or verification against the latest main branch.

Submit a Pull Request (Optional)

Once maintainers confirm the bug and agree on a fix approach, you may contribute a patch. The CONTRIBUTING.md "Before you push" section mandates several checks:

1. Follow the style guide and formatting conventions
2. Include appropriate test coverage
3. Run just prepare_db if your changes touch SQL schemas or queries
4. Reference the original issue number in your PR description

PRs without preceding issues risk rejection regardless of code quality.

Summary

• Always start with an issue – No exceptions per CONTRIBUTING.md
• Use conventional commit titles – bug(component): description format
• Include complete reproductive details – Environment, steps, logs, expected vs. actual
• Escalate security bugs privately – Email security@macro.com, never public issues
• Collaborate actively – Maintainer follow-up speeds resolution
• Prepare PRs properly – Style guide, tests, and just prepare_db for SQL changes

Frequently Asked Questions

What if I'm not sure whether something is a bug?

Open an issue anyway. The maintainers will triage and reclassify if needed. The CONTRIBUTING.md workflow prefers early communication over assumptions about bug status.

How quickly do maintainers respond to bug reports?

Response time varies by issue complexity and maintainer availability. High-quality reports with clear reproduction steps typically receive faster attention. Security reports to security@macro.com are prioritized.

Can I report a bug without a fix?

Yes. Issue-only contributions are valid and encouraged. The workflow explicitly separates issue creation from PR submission to ensure problems are validated before engineering effort is invested.

What database version should I specify in environment details?

Include your Docker compose PostgreSQL version as shown in docker-compose.yml or your running container. Macro targets PostgreSQL 15 as indicated in standard environment configurations.

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