# How to Report Bugs or Issues in the Macro Repository: A Complete Guide

> Learn how to report bugs in the macro repository efficiently. Follow our guide to create effective GitHub Issues with clear steps for a quick resolution.

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

---

**The preferred way to report bugs in the Macro repository is to create a GitHub Issue with a descriptive title, detailed environment information, and a reproducible test case.**

The Macro codebase is an open-source document processing platform built in Rust. When you encounter problems—whether in the document storage service, text extraction pipeline, or API layer—following a structured reporting process helps maintainers diagnose and fix issues faster. This guide shows you exactly how to file effective bug reports in `macro-inc/macro`.

## Search Existing Issues Before Reporting

Duplicate issues waste maintainer time. Always check the [Macro Issues List](https://github.com/macro-inc/macro/issues) first.

- Use keywords related to your error message.
- Filter by labels like `type:bug` or service-specific tags such as `service:document-storage`.
- If you find a related issue, add a comment with your specific details rather than opening a new ticket.

## How to Open a New GitHub Issue in Macro

Once you've confirmed your bug is new, navigate to the Issues page and click **"New issue"**.

### Select the Right Issue Template

The Macro repository provides structured templates. Choose **Bug report** when you have a reproducible problem. Security issues require a different path—see the Security Vulnerabilities section below.

### Write a Descriptive Title

A strong title immediately signals the problem scope. Include the component and symptom:

- ❌ Weak: "Upload broken"
- ✅ Strong: "Document upload fails with `Error 500` on `v2.3.1` in `document-text-extractor`"

## Essential Information for Your Bug Report

Complete issue reports get resolved faster. Include these sections in your issue body:

### Environment Details

Specify your runtime context:

- **OS** (e.g., macOS 14.2, Ubuntu 22.04)
- **Rust toolchain version** (check with `rustc --version`)
- **Docker version** if running containerized (`docker --version`)
- **Macro version** or commit hash

### Steps to Reproduce

Numbered, exact actions that trigger the bug:

1. Start the local stack: `just stack up --no-doppler`
2. Upload a DOCX file via the UI (`/app/upload`)
3. Observe the response error

### Expected vs. Actual Behavior

- **Expected**: The document processes and stores successfully
- **Actual**: API returns 500 with `Internal server error: failed to extract text from DOCX`

### Logs and Relevant Outputs

Attach full error messages and stack traces. For services like `document-text-extractor`, check logs in your terminal or Docker output:

```

2026-08-20T14:32:10Z ERROR document_text_extractor::handler: extraction failed for file_id=1234

```

### Minimal Reproduction Code

Isolate the problem. A small, self-contained snippet proves the bug exists outside your full setup:

```rust
let client = reqwest::Client::new();
let res = client
    .post("http://localhost:8090/app/upload")
    .multipart(form)
    .send()
    .await?;
println!("{:?}", res.text().await?);

```

## Apply Labels and Submit

If you have permissions, tag relevant components:

- `service:document-storage` for issues in [`crates/document-storage-service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/document-storage-service/src/lib.rs)
- `service:document-text-extractor` for text extraction failures in [`crates/document-text-extractor/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/document-text-extractor/src/lib.rs)
- `type:bug` for confirmed defects

Double-check all fields, then click **"Submit new issue"**.

## Monitor and Respond to Follow-Up Questions

Maintainers may request:

- Additional log output
- Confirmation on specific commit ranges
- Testing of proposed fixes

Prompt responses keep your issue moving toward resolution.

## Security Vulnerabilities: Use the Private Channel

**Never report security bugs through public GitHub Issues.** The Macro repository defines a separate process in [[`SECURITY.md`](https://github.com/macro-inc/macro/blob/main/SECURITY.md)](https://github.com/macro-inc/macro/blob/main/SECURITY.md).

Security issues in core services like document storage or text extraction could expose sensitive document data. Follow the private disclosure procedure to protect users.

## Key Reference Files in the Macro Repository

| File | Purpose | Where Bugs Often Originate |
|------|---------|---------------------------|
| [`README.md`](https://github.com/macro-inc/macro/blob/main/README.md) | Project overview and basic setup | Installation problems |
| [`CONTRIBUTING.md`](https://github.com/macro-inc/macro/blob/main/CONTRIBUTING.md) | Contribution guidelines including bug reports | Reporting process questions |
| [`SECURITY.md`](https://github.com/macro-inc/macro/blob/main/SECURITY.md) | Security vulnerability disclosure | Private security reports |
| [`crates/document-storage-service/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/document-storage-service/src/lib.rs) | Core document storage service | Upload failures, permission errors |
| [`crates/document-text-extractor/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/document-text-extractor/src/lib.rs) | Text extraction from documents | DOCX/PDF parsing crashes, encoding issues |

## Summary

- **Search first** to avoid duplicate issues in the Macro repository.
- **Use the bug report template** and write specific, component-focused titles.
- **Include environment, reproduction steps, logs, and minimal code**—this is what makes reports actionable.
- **Tag appropriately** with service labels when possible.
- **Report security issues privately** via [`SECURITY.md`](https://github.com/macro-inc/macro/blob/main/SECURITY.md), never through public issues.

## Frequently Asked Questions

### How do I find the Macro version I'm running?

Check the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) for `version` fields, or look at the Docker image tag if deployed. For local builds, `git log --oneline -1` shows your current commit.

### What if I can't create a minimal reproduction?

Still file the issue. Include as much environment detail and logging as possible, and note that reproduction is intermittent or environment-specific. Maintainers often help isolate the trigger.

### Where are the logs for the document-text-extractor service?

When running via `just stack up`, logs stream to your terminal. For Docker deployments, use `docker logs <container-name>` or check your configured logging sink. The service logs from [`crates/document-text-extractor/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/document-text-extractor/src/lib.rs) use structured logging with `tracing`.

### Can I suggest features through the same issue tracker?

Yes—select the **Feature request** template instead of **Bug report**. Feature requests follow the same principles: clear description, use case, and any implementation ideas you have.