Version Bump

Version Numbers

Currently, Asterinas regularly releases two main artifacts for the Rust OS developer community: the OSDK and OSTD. To support development with these tools, we also publish companion Docker images on DockerHub, (i.e., asterinas/osdk). While the Asterinas kernel is not yet ready for public binary release, its development Docker images (i.e., asterinas/asterinas) are released regularly.

All released crates for OSDK and OSTD share the same version number, which is stored in the VERSION file at the project root. The current content of this file is shown below.

0.14.1

Similarly, the Docker images’ version number is stored in the DOCKER_IMAGE_VERSION file, as shown below.

0.14.1-20250326

We use a custom format for Docker image versions: MAJOR.MINOR.PATCH-DATE. The MAJOR.MINOR.PATCH component aligns with the target version of published crates, while the DATE component allows us to introduce non-breaking updates to the Docker images without publishing a new crate version. Normally, the version in VERSION and the version in DOCKER_IMAGE_VERSION (ignoring the DATE part) are identical, except during the version bump process.

How to Bump Versions

We recommend a three-commit procedure to bump versions:

  1. Commit 1 "Bump the Docker image version" triggers the generation of a new Docker image.
  2. Commit 2 "Switch to a new Docker image" makes the codebase use the new Docker image.
  3. Commit 3 "Bump the project version" triggers the release of new crates.

Depending on your exact purpose, you may complete the version bump process with at most three commits within two PRs.

  • To make non-breaking changes to the Docker images, submit Commit 1 in a PR, then Commit 2 in another.
  • To make breaking changes to the Docker images and the crates' APIs, submit Commit 1 in a PR, then Commit 2 and 3 in another.

Across the three commits, you will be assisted with a convenient utility script, tools/bump_version.sh,

Commit 1: "Bump the Docker image version"

After updating the Docker image content (specified by the tools/docker/Dockerfile.jinja file), increment the Docker image version using the following command:

bump_version.sh --docker_version_file [major | minor | patch | date]

The second argument specifies which part of the Docker image version to increment. Use date for non-breaking Docker image changes. If the changes affect the crates intended to publish, select major, minor, or patch in line with semantic versioning.

This command updates the DOCKER_IMAGE_VERSION file. Submit these changes as a pull request. Once merged, the CI will automatically trigger the creation of new Docker images.

Commit 2: "Switch to a new Docker image"

Creating new Docker images can be time-consuming. Once the images have been pushed to DockerHub, write a follow-up commit to update all Docker image version references across the codebase.

bump_version.sh --docker_version_refs

If your purpose is to publish non-breaking changes to the Docker images, then submit this commit in a PR and then your job is finished. Otherwise, go on with Commit 3.

Commit 3: "Bump the project version"

In this commit, synchronize the version number in VERSION with that in DOCKER_IMAGE_VERSION by running:

bump_version.sh --version_file

This command also updates all version numbers in the Cargo.toml files of all crates scheduled for release. Pack these changes into a third commit and submit the last two commits in a single PR. After the PR is merged into the main branch, the CI will automatically publish the new crate versions.