Developers

Developers

For anyone cloning the repository and submitting PRs. The short version: the invariants below are load-bearing and enforced by tests; the backlog is GitHub Issues; and any change to layout, metrics or fonts is judged by the fidelity method, not by "looks right".

Getting started

git clone https://github.com/nathanpond/n8PDF.git
cd n8PDF
dotnet build n8PDF.sln --configuration Release -warnaserror
dotnet test  n8PDF.sln --configuration Release

Requirements: the .NET 10 SDK. Optional but strongly recommended (required in CI): qpdf (brew install qpdf), fontTools, and FriBidi. If installed, run with them required, because CI will:

N8PDF_REQUIRE_QPDF=1 N8PDF_REQUIRE_FONTTOOLS=1 N8PDF_REQUIRE_FRIBIDI=1 \
  dotnet test n8PDF.sln --configuration Release

Useful commands:

N8PDF_BLESS=1 dotnet test          # re-bless layout goldens after an INTENDED change
tools/make-reference-pdfs.sh       # generate missing Word reference PDFs (macOS + Word)
dotnet pack src/n8PDF -c Release   # the package, with symbols and documentation

Converted fixtures land in artifacts/test-output/ (git-ignored) for eyeballing — they are evidence, not assertions.

Note on CI coverage: 46 of the 143 Word-comparison fixtures need faces only Word ships; hosted CI skips them and says so. A green hosted CI is not the full comparison for anything touching font selection or metrics — see Validation.

The invariants

Do not breach one without it being the explicit, named point of the change:

1. src/n8PDF carries zero PackageReference entries. LibraryInvariantTests fails the build otherwise. Never solve a problem in the library by taking a dependency — System.IO.Compression and System.Xml.Linq are the whole of what is available. A task that seems to need a package needs a conversation instead.
2. The public surface is the eight types PublicApiTests writes out in full (The API). Making anything public is a deliberate act with a diff to show for it — propose it, do not simply do it.
3. Warnings are errors, for every project and every build (Directory.Build.props). While working you may pass -p:TreatWarningsAsErrors=false; never commit in that state.
4. Generated tables are generated. The Unicode tables under Text/ and Fonts/ and the hyphenation patterns are output of tools/make-*-tables.py. Fix the generator and re-run it; never hand-edit the output, and never add a one-off exception in consuming code for something a table got wrong.
5. tools/ means build-input generators — everything in it produces something the project consumes. General-purpose scripts do not belong there.

The fidelity rules

• Never fit a constant to make a test pass. A layout rule is derived, or measured from a probe fixture with its provenance stated. Where a constant is genuinely fitted, that is declared in the code and its gaps stated case by case. Read Matching Word before touching layout.
• A golden updated to match new output proves nothing. A change to layout, metrics or font handling needs its golden diff reviewed — the trace names the run that moved and by how much; you should be able to say why.
• New layout behaviour needs a probe. A feature story should say which fixture proves it; work that cannot be demonstrated against a fixture or golden should say so explicitly and explain how it is checked instead.
• For parsers and decoders, think hostile. Any new code reading document bytes states (and tests) what a crafted input can make it do — see Security for the framing and the existing register.

The backlog is GitHub Issues

On nathanpond/n8PDF — not memory files, not README sections, not TODO comments. If work is worth remembering, it is an issue.

Labels (the list is complete; never invent one — gh label list first):

• Severity for findings: sev:critical, sev:high, sev:medium, sev:low
• Source: security, audit, tech-debt, needs-triage, blocked, epic, documentation
• Kind: feature — a capability that does not exist yet, as against a defect in one that does; it carries no severity

Filing: search first (gh issue list --state all --search "…"); a matching open issue gets a comment, a matching closed one gets reopened. One finding per issue. The body says what, where (path:lines), why it matters, reproduction, suggested fix — and for parser/decoder findings, what a hostile .docx gets out of it. Full filing guidance, including the minimal-reproducing-document ask and the severity definitions, is on Reporting Bugs.

Working an issue

1. gh issue view <n> --comments — all of it.
2. gh issue develop <n> --checkout — a linked branch, recorded by GitHub. CI runs on every branch.
3. Comment a one-line plan on the issue before writing code.
4. Reference the issue in commits as Refs #<n> — never Fixes #<n> (auto-close keywords only fire on the default branch). But beware: a linked branch closes its issue when a PR from it merges anyway, keyword or no keyword. If your merge did not finish the issue, reopen it with a comment saying what is left — check gh issue view <n> --json state after every merge.
5. Verify: warning-clean build, full suite with the three checkers on, goldens reviewed not just regenerated.
6. Push before closing — gh issue close <n> --reason completed --comment "Done in <branch> @ <sha>. <what changed>". A closed issue with no code on the remote is a lie told to every other machine.
7. Cannot finish? Leave it open, comment what blocks it, add the blocked label.

Never: close an issue you did not personally verify; bulk-close; use --reason "not planned" on your own initiative — that is a human's triage call.

Submitting a PR

• Keep it to one issue's worth of work; reference the issue (Refs #<n>).
• The bar is the verification step above: warning-clean, full suite green with checkers on, goldens reviewed, and — for layout work — the probe or fixture that proves the behaviour.
• The release pipeline is tag-driven and versions come from tags only (Promises); PRs never touch version numbers.

Planning larger work

Plan output is issues, not prose: a parent issue labelled epic, children created with --parent <n>, ordering encoded with --add-blocked-by, and each child carrying acceptance criteria as a testable checklist — a story whose criteria cannot be written as something testable is too vague. Stories should be small enough to finish in one sitting, and each feature story names the fixture that proves it.