diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 599ee5de0f..2fab599597 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -303,6 +303,13 @@ By making a contribution to this project, I certify that: this project or the open source license(s) involved. ``` +> **Tip:** If you need to add a DCO remediation commit (e.g., after a force-push +> or rebase), include `[skip ci]` in the commit message so the remediation +> does not trigger unnecessary CI pipelines: +> ```bash +> git commit -s --allow-empty -m 'DCO Remediation Commit for... [skip ci]' +> ``` + #### Utility functions MONAI provides a set of generic utility functions and frequently used routines. @@ -358,6 +365,107 @@ Ideally, the new branch should be based on the latest `dev` branch. 1. Reviewer and contributor may have discussions back and forth until all comments addressed. 1. Wait for the pull request to be merged. +## Skipping CI + +MONAI's CI pipelines run automatically on every push and pull request. +These pipelines can be resource-intensive, especially the full premerge matrix +which spans multiple OSes, Python versions, and PyTorch versions. + +To reduce unnecessary resource consumption and speed up iteration, you can +skip CI on commits that don't need automated validation — for example, +documentation-only changes, README updates, workflow YAML changes, or WIP +commits during development. + +### Mechanism + +GitHub Actions natively supports skipping `push` and `pull_request` workflows +when the commit message contains any of the following strings: + +- `[skip ci]` +- `[ci skip]` +- `[no ci]` +- `[skip actions]` +- `[actions skip]` + +These are case-insensitive. `[skip ci]` is the recommended convention for +this repository. + +Alternatively, you can add a `skip-checks: true` trailer at the end of the +commit message, preceded by two blank lines: + +``` +commit message + +skip-checks: true +``` + +### Usage + +Add the keyword anywhere in the commit message when committing: + +```bash +git commit -s -m 'update docs [skip ci]' +``` + +If the HEAD commit of a pull request contains the skip instruction, +the entire PR's pull_request-triggered workflows are skipped. + +### Which workflows are affected + +The skip instruction applies only to workflows using `on: push` or +`on: pull_request` events. In this repository, that includes: + +- **premerge** (multi-OS lint, tests, packaging, docs build) +- **premerge-min** (minimal dependency matrix) +- **premerge-gpu** (GPU tests) +- **CodeQL analysis** +- **Docker build** +- **Release packaging** +- **Setup/install tests** + +The following workflows use different event types (`issue_comment`, +`repository_dispatch`, `schedule`, `workflow_dispatch`) and are **not** +affected by `[skip ci]`: + +- **Blossom-CI** (triggered by `/build` comment — maintainers only) +- **ChatOps** (triggered by `/black` or `/integration-test` comment) +- **Integration tests** (triggered by `/integration-test` comment) +- **Cron jobs** (scheduled, not per-commit) +- **Weekly preview** (scheduled, not per-commit) +- **Conda build** (scheduled, not per-commit) + +### Important caveat + +If a workflow is skipped via `[skip ci]`, its associated checks remain in +"Pending" state. If your pull request requires those checks to pass before +merging, you will need to push a new commit **without** the skip instruction +to trigger the CI pipelines. + +### When to use + +Use `[skip ci]` for commits that are safe to skip CI: + +- Documentation-only changes (`docs/`, `README.md`, docstrings) +- Workflow configuration changes (`.github/`) +- Repository metadata (`.gitignore`, `CONTRIBUTING.md`, `LICENSE`) +- WIP or draft commits during local development + +Do **not** use `[skip ci]` for commits that change: + +- Source code in `monai/` +- Test files in `tests/` +- Dependencies (`requirements*.txt`, `setup.cfg`, `setup.py`) +- Anything that could affect correctness or compatibility + +### Quick example + +```bash +git commit -s -m 'fix typo in README [skip ci]' +``` + +This commit will be recorded in the repository history but will not +consume CI minutes. + ## The code reviewing process ### Reviewing pull requests