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

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 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:

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
• service:document-text-extractor for text extraction failures in 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).

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	Project overview and basic setup	Installation problems
CONTRIBUTING.md	Contribution guidelines including bug reports	Reporting process questions
SECURITY.md	Security vulnerability disclosure	Private security reports
crates/document-storage-service/src/lib.rs	Core document storage service	Upload failures, permission errors
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, never through public issues.

Frequently Asked Questions

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

Check the root 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 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.

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