版本升級

版本號

目前，Asterinas 定期為 Rust 作業系統開發者社群發行兩個主要的製品：OSDK 與 OSTD。為了支援使用這些工具進行開發，我們也在 DockerHub 上發佈了配套的 Docker 映像檔（即 asterinas/osdk）。雖然 Asterinas 內核尚未準備好發行公開的二進位版本，但其開發用的 Docker 映像檔（即 asterinas/asterinas）。

所有已發行的 OSDK 與 OSTD 軟體箱皆共用同一個版本號，該版本號儲存在專案根目錄的 VERSION 檔案中。該檔案目前的內容如下所示。

0.17.1

同樣地，Docker 映像檔的版本號儲存在 DOCKER_IMAGE_VERSION 檔案中，如下所示。

0.17.2-20260407

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.

如何升級版本

We recommend a three-commit procedure to bump versions:

1. 送交 1「Bump the Docker image version」 會觸發生成新的 Docker 映像檔。
2. 送交 2「Switch to a new Docker image」 會使程式碼庫改為使用新的 Docker 映像檔。
3. 送交 3「Bump the project version」 會觸發發行新的軟體箱。

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

• 若要對 Docker 映像檔進行非破壞性變更，請先在一個 PR 中提交送交 1，接著在另一個 PR 中提交送交 2。
• 若要對 Docker 映像檔和軟體箱的 API 進行重大變更，請在一個 PR 中提交送交 1，然後在另一個 PR 中提交送交 2 和 3。

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

送交 1：「Bump the Docker image version」

更新 Docker 映像檔內容後，請使用以下命令增加 Docker 映像檔的版本號：

./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.

送交 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.

送交 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.