How to Report a Bug in Diagram Design: A Step‑by‑Step Guide

File a GitHub issue with a minimal reproducible example for non‑security bugs, or use GitHub's private vulnerability reporting for security issues.

Diagram Design is an open‑source tool for importing and working with diagram formats like Mermaid and Draw.io. Knowing how to report a bug in Diagram Design the right way helps maintainers reproduce, diagnose, and fix problems faster. This guide walks through the official bug‑reporting workflow as defined in the repository's contributing and security documentation.

When to Create an Issue vs. a Pull Request

The CONTRIBUTING.md file establishes a clear threshold for when an issue is required:

"Create an issue first for anything non‑trivial (new type, behavior change, import grammar work). Small fixes and docs can go straight to a PR."

Follow this decision tree:

• Create an issue first – New features, behavior changes, import grammar modifications, or any bug you cannot fix immediately
• Submit a PR directly – Typo fixes, documentation clarifications, or trivial one‑line corrections

Creating a Public Bug Report

For all non‑security bugs, open a public GitHub issue. The community can then see the problem, discuss reproducibility, and track progress transparently.

Required Components

A high‑quality bug report in Diagram Design should include:

1. Minimal reproducible example – The exact diagram source (Mermaid, Draw.io, etc.) that triggers the failure
2. Command and environment – The full command you ran (e.g., diagram-design import-mermaid …) plus OS, Python version, and installed plugins
3. Observed vs. expected behavior – What you saw, what you expected, and why the difference matters
4. Error output verbatim – The complete error message without truncation

The commands/import-mermaid.md documentation specifically requires that "the extractor exits non‑zero → report its message verbatim and stop." This means copy‑pasting the exact error text is mandatory for valid bug reports involving import failures.

Reference Test Failures

The README.md notes that "If any of these fail, that's a bug worth filing." If you encounter failures in the CI suite or local test runs, include:

• The specific test file name (e.g., verify-mermaid-import.py)
• The failure output or CI run link
• Your local environment details if results differ from CI

Reporting Security Vulnerabilities

Never open a public issue for security‑related bugs. Instead, use the private reporting channel described in SECURITY.md:

"Please use GitHub private vulnerability reporting."

This ensures vulnerabilities are disclosed responsibly and patched before public exposure.

Bug Report Template

Use this structure for your GitHub issues. It satisfies all requirements from the source documentation:

**Title:** `import-mermaid` fails on flowchart with multi-line labels

**Environment**
- OS: macOS 13.6
- Python: 3.11.9
- diagram-design version: 0.9.3

**Steps to Reproduce**

```bash
git clone https://github.com/cathrynlavery/diagram-design.git
cd diagram-design
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
diagram-design import-mermaid examples/bad-flowchart.mmd

Input (bad-flowchart.mmd)

flowchart LR
    A["First line\nSecond line"] --> B
    B --> C["Third line\nFourth line"]

Observed Output

Error: extractor exited with code 2
Invalid label format: multiline labels are not supported in current version.

Expected Behavior The command should succeed, preserving the multiline labels (supported by the latest Mermaid spec).

Additional Context

• The same diagram renders correctly in the Mermaid live editor.
• Running python3 scripts/verify-mermaid-import.py --markdown-only also triggers the same error.

Related Tests The CI suite includes verify-mermaid-import.py; see the failure log in the CI run for reference.

Please let me know if further logs or a minimal repository are needed.

## Key Files for Bug Reporters

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) | Outlines the complete bug‑reporting process, including issue creation thresholds and security‑bug handling |
| [`SECURITY.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SECURITY.md) | Documents the private vulnerability‑reporting channel for security issues |
| [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) | States that test failures constitute bugs worth filing |
| [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) | Defines expected `import-mermaid` behavior and extractor error reporting requirements |
| [`.github/workflows/ci.yml`](https://github.com/cathrynlavery/diagram-design/blob/main/.github/workflows/ci.yml) | Runs the CI test suite; failures here validate bug reports |

## After Submitting Your Report

Once your issue is open:

- Monitor the thread for maintainer requests for additional information
- Be prepared to test suggested fixes on your local environment
- Update the issue with new findings if the problem evolves or you discover additional triggers

## Summary

- **Public bugs** → Open a GitHub issue with minimal reproduction, verbatim errors, and environment details
- **Security bugs** → Use GitHub private vulnerability reporting per [`SECURITY.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SECURITY.md)
- **Trivial fixes** → May go straight to PR without a preceding issue
- **Test failures** → Are explicitly flagged as reportable bugs in [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)
- **Extractor errors** → Must be reported verbatim as required by [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md)

## Frequently Asked Questions

### What information do I need to include when I report a bug in Diagram Design?

Include your operating system, Python version, Diagram Design version, the exact command you ran, the full error output verbatim, and a minimal reproducible example with the diagram source that triggers the failure. The [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) and [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) files emphasize that extractor error messages must be copied without modification.

### Should I file an issue before submitting a pull request?

Depends on the scope. The [`CONTRIBUTING.md`](https://github.com/cathrynlavery/diagram-design/blob/main/CONTRIBUTING.md) states that non‑trivial changes—new types, behavior changes, and import grammar work—require an issue first. Small fixes and documentation improvements can go straight to a pull request without a preceding issue.

### How do I report a security vulnerability in Diagram Design?

Use GitHub's private vulnerability reporting feature. The [`SECURITY.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SECURITY.md) file explicitly instructs: *"Please use GitHub private vulnerability reporting."* Never open a public issue for security‑related bugs, as this could expose unpatched vulnerabilities to attackers before fixes are available.

### What should I do if a test in the CI suite fails?

File a bug report. The [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) states that *"If any of these fail, that's a bug worth filing."* Include the specific test name (such as [`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-mermaid-import.py)), the failure output, and whether the failure occurs locally, in CI, or both.

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