Reporting Bugs

Reporting Bugs

Bugs are tracked in one place: GitHub Issues on nathanpond/n8PDF. Not email, not discussions — an issue is what gets worked, and the tracker is the project's whole backlog.

Before filing

1. Search first, including closed issues — duplicates are the main failure mode of a busy tracker:

   gh issue list --repo nathanpond/n8PDF --state all --search "your distinctive terms"

   If a matching issue is open, comment your evidence there rather than filing again. If it is closed and your case still reproduces, say so in a comment — it may have regressed.

2. Check the scope pages. Something missing from the output may be a documented gap rather than a defect — see Functionality and Known Gaps. Known divergences from Word (the watermark staying searchable text, the residual grid steps, and the rest) are deliberate and held by tests; re-reporting them costs everyone time.

The one thing that matters most: the simplest .docx that reproduces it

Please attach the smallest document that shows the problem. A one-paragraph fixture that reproduces the bug is worth more than a fifty-page report that contains it somewhere, because the whole project runs on minimal fixtures — your reduced document can become the probe that proves the fix and guards it forever (Matching Word).

To reduce a document: make a copy, delete half of it, check the bug still reproduces, repeat. Strip anything that plainly is not involved — other sections, images, tables — until removing anything more makes the bug vanish. What is left is the bug.

Two cautions:

• Do not attach confidential documents. An issue attachment is public forever. Rebuild the reproduction with placeholder text — if the bug survives replacing your content with "lorem ipsum", the content was never part of it.
• GitHub accepts .docx attachments directly; if yours is refused, zip it.

What to put in the issue

• What happened, in a sentence.
• Where, if you know it — a path:lines reference for a code finding, or "page 2, third paragraph" for a layout one.
• Why it matters. For anything in a parser or decoder, state what a hostile .docx gets out of it — memory, CPU, a crash, an aborted conversion. That framing is what the security register is organised around (Security).
• Reproduction: the attached minimal .docx, the call you made (options included), and what came out.
• A suggested fix, if you have one.
• One finding per issue. Never batch — a batched issue can neither be prioritised nor closed honestly.

For fidelity bugs — output that renders, but not where Word puts it — also attach what Word produces for the same document (an exported PDF or a screenshot), and say which Word (platform and version) and which fonts are involved. Fidelity work is measurement, and Word's own output is the reference everything is compared against.

For crashes, hangs or memory exhaustion, include the exception and stack trace (or "hangs after N seconds / grows past N GB"), and note that these are security-relevant even when found by accident — a document that crashes the converter by mistake is a document someone can craft on purpose.

Labels

The vocabulary is deliberately small and complete — GitHub's stock labels were deleted rather than left beside it. Maintainers apply labels, so don't worry about them when filing; they are documented here so the tracker reads unambiguously.

Severity — for findings (defects in what exists)

Label	Meaning
sev:critical	A crafted document kills the process outright — e.g. a StackOverflowException, which .NET cannot catch — or worse.
sev:high	A crafted document can exhaust memory (unbounded or multi-gigabyte allocation) or hang the conversion; or a defect that loses or corrupts content broadly.
sev:medium	A malformed input aborts the whole conversion with an uncaught exception, produces structurally malformed PDF output, or silently corrupts geometry.
sev:low	Latent or off the production path, requires an unlikely input, or a minor behavioural differential.

Source — where the issue came from / what kind of work it is

Label	Meaning
security	A hostile document gets something out of it. Always states what — see Security.
audit	Filed by one of the project's systematic self-audits. Audit issues end with a stable fingerprint comment (<!-- fingerprint: … -->) so the next audit run finds them exactly; external reporters don't need one.
tech-debt	Code that exists is harder to work with than it should be. About the code, not the output.
needs-triage	Recorded but not yet judged — severity and priority still to be decided.
blocked	Cannot proceed until something else lands; the blocker is named in a comment or a blocked-by relationship.
epic	A parent issue grouping children (created with --parent); the tracking unit for multi-story efforts.
documentation	The docs are wrong or missing, not the code.

Kind

Label	Meaning
feature	A capability that does not exist yet, as against a defect in one that does. It carries no severity: a thing that was never built cannot be a sev: of anything — what an absent feature costs is a product judgement, not a measurement of a failure. Distinct from tech-debt, which is about existing code being harder to work with than it should be.

Notes on the scheme:

• Severity applies to findings only. A feature issue never carries a sev: label.
• bug and enhancement do not exist here. bug overlapped the severity scheme (a severity signal split across two vocabularies is worse than either alone), and enhancement straddled defects and absences — the very distinction feature exists to draw.
• Never invent a label. If none fits, say so in the issue and leave it for triage.

What happens next

Issues are worked on linked branches with the fix verified against the full suite — including, for layout bugs, a golden trace or probe fixture that pins the corrected behaviour, which is where your minimal document earns its keep. The workflow, for the curious or the contributing, is on Developers. An issue is closed only when the fix is pushed and personally verified, with a comment saying what changed and where.