Skip to content

Commit 3ee058b

Browse files
garciadiasericspodclaude
authored
docs: add documentation to CONTRIBUTING.md (#8878)
### Description Adds a new "Skipping CI" section to CONTRIBUTING.md documenting the native GitHub Actions commit-message mechanism for skipping CI pipelines. The section covers: - Supported keywords (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `[actions skip]`) - The `skip-checks: true` trailer alternative - Which workflows are affected vs unaffected by the skip instruction - The caveat about required checks remaining in "Pending" state - Guidance on when to (and not to) use `[skip ci]` ### Types of changes - [x] Non-breaking change (fix or new feature that would not break existing functionality). - [ ] Breaking change (fix or new feature that would cause existing functionality to change). - [ ] New tests added to cover the changes. - [ ] Integration tests passed locally by running `./runtests.sh -f -u --net --coverage`. - [ ] Quick tests passed locally by running `./runtests.sh --quick --unittests --disttests`. - [ ] In-line docstrings updated. - [x] Documentation updated, tested `make html` command in the `docs/` folder. --------- Signed-off-by: R. Garcia-Dias <rafaelagd@gmail.com> Co-authored-by: Eric Kerfoot <17726042+ericspod@users.noreply.github.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 184708a commit 3ee058b

1 file changed

Lines changed: 91 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -303,6 +303,13 @@ By making a contribution to this project, I certify that:
303303
this project or the open source license(s) involved.
304304
```
305305

306+
> **Tip:** If you need to add a DCO remediation commit (e.g., after a force-push
307+
> or rebase), include `[skip ci]` in the commit message so the remediation
308+
> does not trigger unnecessary CI pipelines:
309+
> ```bash
310+
> git commit -s --allow-empty -m 'DCO Remediation Commit for... [skip ci]'
311+
> ```
312+
306313
#### Utility functions
307314
308315
MONAI provides a set of generic utility functions and frequently used routines.
@@ -358,6 +365,90 @@ Ideally, the new branch should be based on the latest `dev` branch.
358365
1. Reviewer and contributor may have discussions back and forth until all comments addressed.
359366
1. Wait for the pull request to be merged.
360367
368+
## Skipping CI
369+
370+
MONAI's CI pipelines run automatically on every push and pull request.
371+
These pipelines can be resource-intensive, especially the full premerge matrix
372+
which spans multiple OSes, Python versions, and PyTorch versions.
373+
374+
To reduce unnecessary resource consumption and speed up iteration, you can
375+
skip CI on commits that don't need automated validation — for example,
376+
documentation-only changes, README updates, workflow YAML changes, or WIP
377+
commits during development.
378+
379+
### Mechanism
380+
381+
GitHub Actions natively supports skipping `push` and `pull_request` workflows
382+
when the commit message contains any of the following strings:
383+
384+
- `[skip ci]`
385+
- `[ci skip]`
386+
- `[no ci]`
387+
- `[skip actions]`
388+
- `[actions skip]`
389+
390+
These are case-insensitive. `[skip ci]` is the recommended convention for
391+
this repository.
392+
393+
Alternatively, you can add a `skip-checks: true` trailer at the end of the
394+
commit message, preceded by two blank lines:
395+
396+
```
397+
commit message
398+
399+
skip-checks: true
400+
```
401+
402+
### Usage
403+
404+
Add the keyword anywhere in the commit message when committing:
405+
406+
```bash
407+
git commit -s -m 'update docs [skip ci]'
408+
```
409+
410+
If the HEAD commit of a pull request contains the skip instruction,
411+
the entire PR's pull_request-triggered workflows are skipped.
412+
413+
### Which workflows are affected
414+
415+
The skip instruction applies only to workflows triggered by `on: push` or
416+
`on: pull_request` events. All other workflows — those using `issue_comment`,
417+
`repository_dispatch`, `schedule`, or `workflow_dispatch` — use different
418+
event types and are **not** affected by `[skip ci]`.
419+
420+
### Important caveat
421+
422+
If a workflow is skipped via `[skip ci]`, its associated checks remain in
423+
"Pending" state. If your pull request requires those checks to pass before
424+
merging, you will need to push a new commit **without** the skip instruction
425+
to trigger the CI pipelines.
426+
427+
### When to use
428+
429+
Use `[skip ci]` for commits that are safe to skip CI:
430+
431+
- Documentation-only changes (`docs/`, `README.md`, docstrings)
432+
- Workflow configuration changes (`.github/`)
433+
- Repository metadata (`.gitignore`, `CONTRIBUTING.md`, `LICENSE`)
434+
- WIP or draft commits during local development
435+
436+
Do **not** use `[skip ci]` for commits that change:
437+
438+
- Source code in `monai/`
439+
- Test files in `tests/`
440+
- Dependencies (`requirements*.txt`, `setup.cfg`, `setup.py`)
441+
- Anything that could affect correctness or compatibility
442+
443+
### Quick example
444+
445+
```bash
446+
git commit -s -m 'fix typo in README [skip ci]'
447+
```
448+
449+
This commit will be recorded in the repository history but will not
450+
consume CI minutes.
451+
361452
## The code reviewing process
362453
363454
### Reviewing pull requests

0 commit comments

Comments
 (0)