Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
67 lines (48 loc) · 2.71 KB

CONTRIBUTING.md

File metadata and controls

67 lines (48 loc) · 2.71 KB
Raw

Contributing to TileWright

Thanks for looking. This is a small, sharp tool and the aim is to keep it that way.

The most useful thing you can send

A pattern PDF that TileWright gets wrong.

Real files from real design tools are worth more than any feature request. If a pattern doesn't tile cleanly, open an issue with:

  • what produced the PDF (Illustrator, Inkscape, Affinity, Seamly2D, CLO3D, a plotter driver, a scanner…)
  • what you expected and what you got
  • the output of node cli.js yourfile.pdf --info
  • the file itself, if you can share it — a cut-down repro is fine, and if the pattern is commercial, please don't upload it; describe it instead

Layer handling in particular has many shapes in the wild (nested groups, radio button groups, usage dictionaries, per-page /OCProperties variants). Every odd file makes the parser better.

Running things

node test/run.js                      # the whole suite, no dependencies
node examples/make-sample-pattern.js  # regenerate the layered fixture
node build.js                         # rebuild dist/tilewright.html

There is no install step and no node_modules. pdf-lib and pdf.js are vendored in vendor/ on purpose: the tool has to keep working offline, from a file:// URL, years from now.

House style

  • ES5, no build step for src/. The same files run in Node and in the browser via a small UMD wrapper. Please keep it that way.
  • No new runtime dependencies. If something genuinely needs a library, open an issue first and let's talk about vendoring it.
  • Pure logic stays pure. units.js and grid.js know nothing about PDFs and must remain trivially testable.
  • Comments explain why, not what. The interesting comments in this codebase are the ones recording a trap (array /Contents, the /Producer rewrite, the 4in/10cm collision). Add to that record.

Tests

Anything touching geometry or layers needs a test. The suite is a ~60-line harness in test/harness.js — test(), assert.equal/close/deepEqual/throws.

Two tests are load-bearing and should never be weakened:

  • grid: THE INVARIANT — tiles cover every point of the source
  • REGRESSION: a naive embed loses /OCProperties

The second one deliberately reproduces the bug this project exists to fix. If it ever starts passing trivially, the regression it guards has stopped being tested.

Scope

TileWright tiles one page well. It is deliberately not a pattern editor, a grading tool, or a marketplace. Things that fit: better layer handling, more paper sizes, projector output, blank detection in Node, SVG input. Things that don't: drafting, nesting for production, cloud sync, accounts.

By contributing you agree your work is MIT licensed.