Contributing

How to set up, make a change, and get it merged.

Issues and pull requests are welcome. This section covers the code; for using Marrow, start at Getting started.

Setup

Requires Node.js ≥ 24.

git clone https://github.com/raiz-toff/Marrow.git
cd Marrow
npm install
npm run compile
npm test          # 244 tests should pass

The aws/azure/gcp icon packs are fetched on demand and are not required to build or to run the tests:

npm run marrow -- icons fetch --yes

The development loop

  1. Make the change in the relevant packages/* module.
  2. npm run compile — TypeScript project references plus the runtime bundle.
  3. npm test — add or update tests for any behavior you changed.
  4. For anything affecting rendered output, look at it:
npm run marrow -- snapshot fixtures/valid/small-office.yaml -o /tmp/x.png

The corpus fixtures under fixtures/ are the enforcement layer for visual work — the geometry linter runs over them in the test suite.

Ground rules

Determinism is a hard requirement. Builds must be reproducible byte-for-byte. No nondeterministic ordering, no timestamps, no randomness in build output. Sort by id when order would otherwise be arbitrary.

Diagnostics stay machine-readable. A new validation error carries a code from the registry, a YAML path, line and column, a fix hint, and did-you-mean suggestions where they help. Codes are never renumbered or reused — agents and tests key off them.

Both renderers must match. Every visual change lands in render-svg andcanvas-engine, plus packages/site/src/styles.ts. A change in one renderer only is a bug that appears at a device-count threshold.

Never hand-edit generated trees. output/, **/dist/, fetched vendor icon SVGs.

Icons. Don't commit AWS/Azure/GCP SVGs — they're user-fetched for licensing reasons. (cisco is committed — it's jgraph's Apache-2.0 draw.io stencils, not Cisco artwork.) New icons must be under a permissive or attributed license, with the attribution recorded in icon-packs/LICENSES.md.

No framework dependencies in the viewer. The diagram chrome is shadcn/ui ported to vanilla CSS and TypeScript, never installed as React components. Outputs must stay single-file, zero-dependency, offline HTML — framework weight taxes every exported diagram. When porting a shadcn component, take its literal token values and metrics from the upstream source rather than approximating.

Pull requests

  • One logical change per PR.
  • npm run compile && npm test green — CI runs the same on every PR.
  • Describe the user-visible effect and how you verified it. For visual changes, attach the snapshot.

Reporting bugs

Use the GitHub issue templates. For a bug, a minimal .yaml that reproduces it is the single most useful thing you can include.

Documentation

This site is the canonical documentation and lives in docs/:

npm run docs           # dev server
npm run docs:build     # production build + Pagefind search index

If you change the schema, the CLI surface, or the diagnostic registry, update the Reference pages in the same PR — that's where those facts live now. Root files like README.md and AGENTS.md deliberately point here rather than restating.

Code of Conduct

This project follows the Contributor Covenant.

License

Contributions are licensed under the project's MIT License.

Edit this page
Rules for agents
The non-negotiables when an agent is driving Marrow.
Architecture
How YAML becomes an interactive diagram — the compile pipeline, stage by stage.