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

> Report bugs in Macro effectively using the official GitHub issue workflow. Learn the exact format for clear bug reporting and how to handle security vulnerabilities privately.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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

```markdown
bug(<component>): short description

```

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

```markdown
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

```markdown

# 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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/docker-compose.yml) or your running container. Macro targets PostgreSQL 15 as indicated in standard environment configurations.