Contributing

Contribute focused changes with synthetic test data, verify the highest boundary you touched, and update user-facing documentation when behavior changes.

Understand implementation boundaries

• Runtime internals maps process dispatch, local startup, the async/blocking boundary, cache ownership, and shutdown.
• Internal HTTP protocol records the unsupported viewer routes, executable contract, cache headers, errors, and cross-origin debugging feature.

These pages are for source maintenance. Users should begin with Sessions and viewer lifetime and the supported interfaces.

Protect sensitive data

DICOM objects, screenshots, paths, logs, tags, and annotation CSVs can contain protected health information, research identifiers, institution names, hostnames, or other sensitive data.

Do not put real or unapproved clinical data in issues, pull requests, fixtures, screenshots, or CI artifacts. Use repository-generated fixtures, redacted logs, or minimal reproduction steps. Report suspected vulnerabilities privately through the source repository’s security policy.

Prepare a source checkout

The v0.4.1 development baseline requires:

• Rust 1.88 or later;
• Node.js 20.19 or later and npm;
• CMake and a C++ toolchain for statically linked CharLS;
• Python 3.9 or later.

git clone https://github.com/dcmview/dcmview.git
cd dcmview
npm --prefix frontend ci
cargo build

Cargo invokes the frontend build and embeds frontend/dist into the binary. During backend-only iteration, skip it only when an existing frontend/dist/index.html is present:

DCMVIEW_SKIP_FRONTEND_BUILD=1 cargo check --locked

Choose a check profile

The repository check driver composes the supported verification boundaries.

Profile	Use it for	Contents
quick	Fast local feedback	Version/contract checks, frontend types/tests/build, strict Rust format and lint, and Python unit tests. It does not run Rust tests.
core	Deterministic shared behavior	quick, fixture regeneration stability, the default-feature locked Rust suite, and VS Code compilation.
e2e	Process and integration changes	core plus real debug binary, HTTP smoke, Python real-binary, and VS Code Electron integration.
external	Independent upstream fixtures	Exactly the feature-gated ignored remote-fixture tests; it may download or cache data.
corpus	A local prepared corpus	Ignored library and integration tests against a locally generated corpus passed with --corpus; it fails when the path is missing.

python scripts/check.py quick --install
python scripts/check.py core --install
python scripts/check.py e2e --install
python scripts/check.py external
python scripts/check.py corpus --corpus /path/to/prepared-corpus

Run at least core when changing shared HTTP contracts, server behavior, pixel decoding, generated types, or fixtures. Use e2e for startup, Python wrapper, bridge, smoke, or VS Code integration changes.

Targeted commands remain useful during iteration:

DCMVIEW_SKIP_FRONTEND_BUILD=1 cargo test --workspace --locked
npm --prefix frontend run generate:types
npm --prefix frontend run check:contracts
npm --prefix frontend run typecheck
npm --prefix frontend run test
python -m unittest discover -s python/tests

The repository is a Cargo workspace whose root is also the dcmview package. Without --workspace, cargo test and cargo clippy cover only that package and skip the member crates under crates/. crates/dcmview-protocol owns the launch and startup contract.

Use synthetic DICOM fixtures

Committed fixtures under tests/fixtures/ are small, synthetic, and generated by repository code:

cargo run --example generate_test_fixtures

Fixture regeneration must leave the committed tree unchanged unless the change deliberately updates a fixture and its assertions. Integration tests should exercise the real DICOM layer instead of mocking parsing, metadata, codecs, or pixel transport.

Remote fixtures stay behind the remote-fixtures feature and the external profile because they may download or cache upstream data.

Preserve architecture contracts

Update the source repository’s normative architecture document when module ownership, dependency direction, lifecycle ownership, HTTP contracts, or check profiles change.

Important boundaries include:

• keep discovery and decode work out of the async executor;
• never hold a cache lock during filesystem, codec, encoding, or serialization work;
• change src/api/contracts.rs before regenerating frontend API types;
• use the shared JSON error envelope for extractor and handler failures;
• keep server and browser windowing in agreement with the shared tests/windowing-cases.json oracle;
• keep semantic interpretation separate from stored-pixel preview;
• retain loopback as the default bind and its public-bind warning path; and
• keep every /api route behind the access token check.

The runtime internals page explains how these boundaries fit together. The source repository’s docs/architecture.md remains normative when this site and the release source differ.

Update public documentation

Update this site when a stable release changes installation, CLI options, Python behavior, VS Code settings, environment variables, annotation CSV semantics, HTTP behavior, DICOM support, or troubleshooting.

The documentation repository uses Node.js 24 through .nvmrc; Node.js 22.19 or later is supported.

git clone https://github.com/dcmview/dcmview-docs.git
cd dcmview-docs
npm install
npm run develop

Before a documentation pull request:

1. Read docs-source.json and verify claims against its exact source tag and commit.
2. Keep procedures in Guides, durable explanations in Concepts, and exact values in Reference.
3. Use fenced code blocks with explicit canonical language identifiers.
4. Run the required checks.

npm run format
npm run validate

When synchronizing a new stable release, update every affected page and all fields in docs-source.json in the same pull request. The stable source follows GitHub’s latest non-draft, non-prerelease release by creation time—not the highest semantic version or the source repository’s default branch.

Open a focused pull request

Describe the behavior or documentation changed, the checks run, known limitations, and confirmation that no sensitive data is included. Keep unrelated refactors out of a focused fix or feature.