Skip to content

CONTRIBUTING.md: Describe commit keywords #12211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

CONTRIBUTING.md: Describe commit keywords #12211

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3cea737
CONTRIBUTING.md: Describe commit keywords
eschnett Oct 2, 2025
13c4858
Add @giordano's suggestions
eschnett Oct 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 22 additions & 4 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,28 @@ are not descriptive (virtually all pull requests update a file called `build_tar

#### Special keywords in commit messages

Anywhere in a commit message you can use the special keyword `[skip build]`, which has a two-fold effect:
There are two special keywords in commit messages, `[skip build]` and `[skip ci]`. These keywords can be anywhere in a commit message. Do not put these keywords into the first line (the header) since these instructions are a technical detail that isn't relevant when looking at a summary of many commit messages.

These keywords are examined by our build system for every push made to the repository. They can be in any of the commit messages that make up a push. Keywords in existing, earlier commits are ignored when examining a push. That is, when making several pushes, each push needs to contain a commit that contains these keywords.

`[skip build]` has two following effects:
* in pull requests, the touched packages will not be built.
* for commits pushed to the default (`master`) branch, including merging a branch to the default branch: Although the touched packages will not be built, a new version of the correspoding JLL packages will be published, using as artifacts those of the previous build with the same `x.y.z` version number. The build number will be increased by one. (This is only interesting for maintainers when merging a branch into the master branch; see section "Information for maintainers" below.)

`[skip ci]` has the following effect (this keyword is only interesting for maintainers when merging a branch into the master branch; see section "Information for maintainers" below):
* in pull requests, this has no effect.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not entirely sure this is true: I've seen many cases where CI just doesn't run in pull requests, effectively making them unmergeable. The reason why this wasn't documented in this section is because users should just not use it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even if normal users shouldn't use it, I think it is good to document it for maintainers, because I always seem to forget the difference between the two and where each one needs to go.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but it's documented below.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's documented on a long page. That documentation begins with "`[skip ci] to not run CI at all [...]". That fooled me. (The sentence continues with a clause that explains that the "not at all" does not always apply.)

There is also a section titled "Special keywords in commit messages". It mentions only [skip build]. The other keyword, [skip ci], is only described further down.

I am updating this page because I find it confusing, and I regularly make mistakes using these keywords. Hence the two new subsections called "How to [...]".

* for commits pushed to the default (`master`) branch, including merging a branch to the default branch: CI will not be run at all.

##### How to make a single change to a pull request without triggering a build

* Use `[skip build]` in the commit message

##### How to change a package without releasing a new version (and without building the package)

* Create a pull request
* Use `[skip build]` in every commit message for the pull request
* The maintainer must merge with `[skip ci]`

* in pull requests, a build of the touched packages will not be performed
* for commits pushed to the default branch, a new build of the touched packages will not be performed but a new version of the correspoding JLL packages will be published, using as artifacts those from the latest registered versions of the packages (the build number will be increased by one).

### Understanding build cache on Yggdrasil

Expand Down Expand Up @@ -115,5 +133,5 @@ Here are some recommendations for Yggdrasil maintainers:
There is little need to preserve full history of individual pull requests.
This also makes sure special keywords in commit messages are part of the commit which triggers the CI workflow and so they can have effect
* use special commit message keywords as appropriate:
* `[skip ci]` to not run CI at all when merging a pull request
* `[skip build]` to only update the JLL wrapper of a package without rebuilding the package once again
* `[skip ci]` to not run CI at all when merging a pull request. This keyword has no effect when pushing to a branch; it is only relevant when merging a pull request.