Contributing

Contributing

This page describes how to prepare a focused contribution, verify it and hand it over for review.

ChemDraft welcomes changes that make drawing more reliable while keeping the core small, testable and legally redistributable. A complete contribution includes its platform behavior, meaningful regression checks and documentation. A feature that works only on macOS or only on Windows is not ready to merge.

Before you change code

1. Read AGENTS.md, PLANS.md, README.md, root package.json and pnpm-workspace.yaml.
2. Read the README for each affected package, plus current architecture notes for the subsystem.
3. Check recent entries in docs/shipped/ before treating an older decision as current behavior.
4. For a new feature, dependency, licensing decision or user-facing surface, consult PLAN.md for scope.
5. For selection or hit-testing work, read docs/shipped/selection-policy-refactor.md first.

PLANS.md describes active work, not a general backlog to implement at will. Parked items need a reason recorded before reopening. If the proposed fix needs a broader behavior change, make that scope explicit rather than extending a narrow patch silently.

Some READMEs still describe the foundation milestone. Confirm actual status in code and newer shipped records. The product charter's non-goal list is not proof that a later optional plugin capability does not exist.

Use your own branch and worktree

Work only in the checkout for your branch. main is protected, and changes land by pull request with green CI. Check the active branch before committing, particularly when multiple contributors share an environment. Stage explicit paths so unrelated work is not included.

Branch builds are separate development applications with separate identifiers, app data and single-instance locks. Never overwrite, rename or unregister the stable installed app. Follow Building from Source and report the worktree label you actually launched.

Keep the implementation in its owner

Use Package Map to choose the right package. In particular:

• Native types, validation and patches belong in chem-core.
• Molecule rendering math and label grammar belong in layout-engine.
• Shared app/CLI/MCP document builders belong in document-workflow-core.
• Operating-system behavior stays behind the desktop native boundary.
• Plugin-facing contracts belong in plugin-api, with permissions enforced by plugin-host.

Use registered commands or typed host capabilities for every extension action. Do not add a hidden route to React state, private functions or the DOM. Plugin and agent edits go through patches and the appropriate direct-insertion or proposal-review gate.

Preserve chemical meaning across every conversion. Style and layout changes must not change the graph. A conversion that cannot retain a radical, isotope, charge or stereochemical distinction warns or fails; it does not quietly replace the structure.

Build both sides together

Shared code is the default. Where the operating system forces a split, implement both sides in the same change. Rust platform branches need their corresponding other-platform behavior and clippy must pass with warnings denied on both hosts.

For TypeScript shortcut differences, accept a platform parameter defaulting to detection so one test host can exercise both branches. Windows paths, file locks, line endings and native focus need their own attention. New cross-platform repository scripts use Node rather than shell-specific syntax.

Native windows and dialogs must be document-owned. Windows attaches menus only to the document window, while macOS uses an application-wide menu. See macOS and Windows Differences before changing this boundary.

Write honest public text

Call the application ChemDraft. Do not name or compare commercial competing chemical-drawing products in public prose, commit messages or PR text. File-format names such as CDXML are fine. Reserve MolScribe for the external recognition project and its optional OCSR plugin.

Use original or legally redistributable icons, fixtures, templates and documentation. Add a new vendored binary to NOTICE and the dependency inventory in the same change. Software and dataset licences are separate: an MIT code licence does not automatically license a bundled database.

Analysis values need method contracts and honest status. Label estimates as estimates. Recognition remains experimental and reviewable. Do not publish accuracy percentages without their measured partition and reproducible evidence.

Tests, PR and closeout

Run the Testing and CI gauntlet, relevant scoped checks and the standing manual checklist for interactive changes. Runtime changes require a build-stamp bump. Launch the result from your worktree, and state exactly which platform checks ran.

Describe the concrete problem and resulting behavior in the PR. A before/after example is useful when it makes the fix reviewable. Include relevant test results and limitations; omit conversational history. A completed implementation slice moves from PLANS.md to docs/shipped/README.md.

Use this closeout format: Summary, Files changed, Tests run, Results, Platforms, Known limitations, and One recommended next task. Name macOS and Windows separately as verified or unverified, with the remaining checks. Skipped checks are not passes.

See also

• Developer Guide
• Testing and CI
• Project Rules
• Licensing and Notices