Contributing

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

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.2.12 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; and
• ssh only when testing tunnel behavior.

git clone https://github.com/beatrice-b-m/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.

python scripts/check.py quick --install
python scripts/check.py core --install
python scripts/check.py e2e --install
python scripts/check.py external

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 --locked
npm --prefix frontend run check:contracts
npm --prefix frontend run typecheck
npm --prefix frontend run test
python -m unittest discover -s python/tests

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 semantic interpretation separate from stored-pixel preview; and
• retain loopback as the default bind and its public-bind warning path.

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/beatrice-b-m/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.