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:
- Commit 1 "Bump the Docker image version" triggers the generation of a new Docker image.
- Commit 2 "Switch to a new Docker image" makes the codebase use the new Docker image.
- 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.