Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (69 loc) · 5.52 KB

CONTRIBUTING.md

File metadata and controls

105 lines (69 loc) · 5.52 KB
Raw

Contributing to SliM

Thank you for your interest in this application. This document provides further technical information about the app and guidelines on how to contribute to its development.

User interface design and logic

The UI is designed for an image-centric digital pathology workflow based on the DICOM standard.

Core UI components

  1. Worklist: lists cases (DICOM studies) at /
  2. CaseViewer: lists digital slides of a selected case (DICOM series of a selected DICOM study) at /studies/:StudyInstanceUID
  3. SlideViewer: facilitates interactive visualization of a multi-resolution pyramid of a whole slide image (DICOM image instances of a selected DICOM series) at /studies/:StudyInstanceUID/series/:SeriesInstanceUID

User flow

The Worklist queries the origin server for available imaging studies and renders query results as a table, where rows are individual studies and columns are study-level image attributes. Upon selection of a study by the user, the app routes the user to the CaseViewer, which queries the origin server for available series for the selected study. The CaseViewer displays selected patient- and study-level attributes that are shared amongst image instances in the selected study across the different series and lists individual series, showing the container identifier and OVERVIEW image (if available) for each item. Upon selection of an individual series, the app routes the user to the SlideViewer, which displays the VOLUME images and the LABEL image (if available) of the selected series along with specimen-related attributes that are shared amongst the image instances in the selected series. The app automatically selects the first series of the study, but the user can select other series from the list displayed in the CaseViewer. The SlideViewer further provides annotation tools, which enable the user to draw, modify, select, remove, or save region of interest (ROI) annotations.

Implementation details

The app is implemented in TypeScript using the React framework. The antd React UI component library is used with a customized theme.

The app is built using craco (with the craco-less plugin), which serves as a configuration layer around create-react-app.

Tests are written and run using the jest framework.

The pnpm package manager is used to manage dependencies and run scripts specified in package.json (build, lint, test, etc.).

Coding style

Source code is linted and formatted using Biome. TypeScript is used with strict type checking compiler options enabled. Semicolons are not used at the end of statements (Biome uses asNeeded).

Explanatory comments use JSDoc-style block comments (/** … */), not // line comments. Keep // only for tooling directives (eslint-disable, @ts-expect-error, biome-ignore), temporarily commented-out code, and shebang lines.

Use the following commands to check and fix style:

$ pnpm run lint        # check for issues
$ pnpm run lint:fix    # auto-fix issues
$ pnpm run fmt         # format code

Documentation

Every function and method (with the exception of standard React.Component methods such as render() and componentDidMount()) shall have a docstring in JSDoc format:

/**
 * Check values.
 *
 * @param options - Options
 * @param options.foo - One option
 * @param options.bar - Another option
 *
 * @returns The return value
 */
const checkValues = ({ foo, bar }: { foo: string, bar: number }): boolean => {}

The types of parameters and return values are omitted in docstring comments, given that type annotations are already available in TypeScript.

Pull requests

Use the repository pull request template. Include a clear summary, testing notes, and a semantic-release style title (for example feat(Worklist): …, fix(SlideViewer): …).

Pairing a Firebase preview with dicom-microscopy-viewer

If your Slim change depends on an unreleased dicom-microscopy-viewer branch, the Firebase preview workflow can install that branch automatically.

There are two ways to link a DMV branch (both require an open PR in DMV):

  1. Explicit dmv-branch: — add a line near the top of the PR body:

    dmv-branch: feat/my-dmv-change

  2. Matching branch name — use the same branch name in both repos (for example feat/my-change in both Slim and DMV). No configuration needed — the workflow detects matching branches automatically.

If both methods apply, dmv-branch: takes priority. If neither applies, the preview uses the published npm version from package.json.

PR comments

The workflow automatically posts a comment on your PR indicating which DMV version the Firebase preview is using:

  • Linked to DMV Branch — shows the branch name, commit SHA, and source (explicit dmv-branch: or matching branch name)
  • Using Published DMV — shows the version from package.json

Retriggering the preview

Editing the PR description to add or change dmv-branch: retriggers the Firebase preview workflow (body edits only; title-only edits are ignored).