Skip to content

Contributing

The Clinical AI Curriculum is built to be forked, adapted, and improved by other clinical educators. This page explains how.

Who contributes here

Three audiences:

  1. Clinical educators running a similar workshop or cohort and adapting the material (different dataset, different institutional context, language translation).
  2. Learners who spotted a bug, a confusing explanation, a broken link, or a better way to phrase a clinical analogy.
  3. AI/ML practitioners improving the technical scaffolding (newer foundation models, better calibration techniques, alternative explainability methods).

All three are welcome. The contribution flow is the same.

Before opening a pull request

  1. For non-trivial changes, open an issue first. Especially for new chapters, alternative datasets, or large refactors. This avoids you investing hours into something the project would not accept, and avoids two contributors duplicating work.
  2. For typos, broken links, small clarifications: a direct PR is fine, no issue needed.
  3. For language translations of the glossary or notebook markdown cells: please open an issue first so we can coordinate. The translation is a substantial undertaking; we want to make sure your version becomes the canonical translation rather than fragmenting effort.

The mechanics

This is a standard GitHub flow:

  1. Fork the repository.
  2. Create a feature branch from main (e.g. git checkout -b fix/ch7-gradcam-target-layer).
  3. Make your changes.
  4. If you changed the notebook, validate it still parses: python -c "import json; json.load(open('notebook/Clinical_AI_2026.ipynb'))".
  5. If you changed demo/app.py: python -m py_compile demo/app.py.
  6. Commit with a "why-focused" message (the change should be self-explanatory; the message explains the motivation).
  7. Open a PR against main.

CI runs three checks on every PR:

  • Link check confirms every URL referenced from the repo still resolves.
  • Notebook smoke runs the dependency-import and dataset-load cells (everything before the first gpu-required-tagged training cell) on a CPU runner.
  • Documentation build confirms the mkdocs site still builds cleanly.

A maintainer will review within a few days. We optimise for "small, focused, well-explained" over "large and exhaustive": a PR that fixes one chapter's GradCAM target layer is more likely to be merged than a PR that rewrites three chapters at once.

Style guide

  • No em dashes (—, U+2014). Use a hyphen with spaces (-), a comma, or a colon.
  • One-sentence-per-line markdown is preferred in the docs but not enforced.
  • Notebook markdown cells should lead with a clinical analogy or motivating question, then the code, then the discussion of the output. Never assume the learner knows programming jargon.
  • Notebook code cells should have inline comments explaining each non-trivial line. The audience is Python beginners.

Adapting the curriculum for your own cohort

You do not need to PR back to the canonical repo to teach this material. Forking is encouraged. A typical adaptation:

  1. Fork this repo into your institution or personal namespace.
  2. Pin a release tag for your cohort so you can keep teaching the same version while the canonical repo evolves: git tag v2027-cohort && git push origin v2027-cohort.
  3. Update the Colab badge URL in your fork's README to point at your tag.
  4. Change the dataset in notebook/Clinical_AI_2026.ipynb Chapter 1 if you want to use your own institutional data (subject to all the usual licensing, IRB, and PHI constraints).
  5. Re-run scripts/publish_dinov2_mednist.py against your own HF namespace to publish a fork-specific model card.

If you publish your fork, please open an issue here linking it. We are collecting a list of institutional adaptations.

What we will not accept

To keep the curriculum focused:

  • PRs that turn the curriculum into a clinical decision tool. This is a research lab, not a 510(k) submission. The disclaimers are deliberate.
  • PRs that remove the failure-modes pedagogy. It is the spine of the curriculum.
  • PRs that introduce non-open-source dependencies. Everything has to run on a free Colab T4 with public datasets.

Code of Conduct

We follow a Code of Conduct. Be kind, assume good faith, and remember that the audience for this material is busy clinicians.

Recognition

All contributors are credited in the next release notes. For substantial contributions (a new chapter, an institutional adaptation), we will add you to CITATION.cff as a co-author of the relevant version.