Contributing

Note

The repository is not public yet. Until it is, the routes below are the ones that exist: get in touch by email, and the rest of this page tells you what to expect when it does open up.

Reporting something

The most useful bug report for this project contains:

• The .openchip file. It is plain JSON and it carries the printer profile, so it reproduces exactly what you were looking at.
• What you expected and what happened.
• Your browser and version, if it is a rendering or a save issue.

For a wrong number — a pressure estimate, a warning threshold, a fluid property — include what you measured and how. A measured contradiction is the most valuable thing anyone can send this project, and it will be acted on.

Contact: juliancimoca@gmail.com. An issue tracker will replace this when the repository is public.

The non-negotiables

Four rules that shape everything. A change that breaks one of them will not be accepted, however good it is otherwise.

Nothing ever blocks the user

The Design checks panel has no way to express “blocked”, and it has no relationship to the export buttons. Every finding is a warning that states what was measured and what tends to go wrong, and then leaves the decision alone.

This is absolute. See Design checks.

No network at runtime

No backend, no database, no auth, no fetch. The app must work offline once loaded, and nothing a user draws may leave their machine.

Templates are static data compiled in, not fetched. Fluid properties are constants, not an API.

Every parameter is editable somewhere

Advanced controls may be tucked behind a disclosure. They may not be omitted. A scientist with an edge case must be able to reach the number.

Honest about limits

Where a figure is a rule of thumb, the app says so. Where a model does not include something, the app says so on the same screen. A template that approximates a published device carries a caveat describing exactly what it approximates.

Working on the code

npm install
npm run dev

Before pushing anything:

npm run build && npm test && npm run lint

npm run build runs tsc -b first, so a type error fails the build.

Things that will bite you

• erasableSyntaxOnly is on. No TypeScript parameter properties (constructor(private x: T)), no enums. This has broken a deploy before.
• Test files must use relative imports. An absolute machine path in a test breaks the build on a clean clone.
• Preset node ids are deterministic, not UUIDs. That is what lets a thumbnail render without touching the store and lets presetBuild() be memoised safely. A non-deterministic builder turns that cache into a bug.
• presets.test.ts asserts no template opens with a risk-severity warning. A starter chip that greets a new user with red teaches them to ignore the panel. Any template you add must pass that file unchanged.

Changing a check or a threshold

1. Change the code.
2. Update the design-check catalogue — every WarningKind needs an anchored section, and npm run wiki:audit enforces it.
3. Add the entry to src/lib/wikiLinks.ts if the kind is new. The Record<WarningKind, string> makes this a type error if you forget.
4. Grep the whole wiki for any number you changed. sourceRefs will not find every page that quotes a default.

See How this wiki is maintained.

Changing the file format

Additive changes only, and new fields must be optional with a documented default. A file written by a newer build has to open in an older one, and unknown fields have to survive a save round-trip. Silently deleting a user’s data because they opened a file in last month’s build is not acceptable.

Then update the format reference — the audit checks every field in src/types/project.ts appears there.

Documentation

Changes to this wiki follow the contract on How this wiki is maintained. The short version: full frontmatter, populated sourceRefs, and npm run wiki:audit passes.

Licence

To be confirmed. Until a licence is chosen, no permissions are granted beyond what you have been given directly.