diff --git a/docs/website/docs/developers/general/versioning-scheme.md b/docs/website/docs/developers/general/versioning-scheme.md new file mode 100644 index 000000000000..5267e33f628f --- /dev/null +++ b/docs/website/docs/developers/general/versioning-scheme.md @@ -0,0 +1,72 @@ +--- +icon: octicons/versions-16 +--- + +# Versioning scheme + +A shared version format is used for the packages + +* `iree-base-compiler` (formally named `iree-compiler`) +* `iree-base-runtime` (formally named `iree-runtime`) +* `iree-turbine` + +## Overview + +Type of build | Version format | Version example +------------- | -------------- | --------------- +Stable release (PyPI) | `X.Y.Z` | `3.0.0` +Nightly release (GitHub `schedule`) | `X.Y.ZrcYYYYMMDD` | `3.0.0rc20241029` +Dev release (GitHub `pull_request`) | `X.Y.Z.devNN` | `3.0.0.dev+6d55a11` +Local build | `X.Y.Z.devNN` | `3.0.0.dev+6d55a11` + +### Key + +Identifier | Explanation +---------- | ----------- +`X` | Major version +`Y` | Minor version +`Z` | Patch version +`rc` | release candidate (`main` branch) +`dev` | developer build (code on pull request branches) +`YYYY` | Year, e.g. `2024` +`MM` | Month, e.g. `10` +`DD` | Day, e.g. `29` +`NN` | git commit hash, e.g. `6d55a11` + +## Composition of version numbers + +A release number is in the format of `X.Y.Z` (MAJOR.MAJOR.PATCH) + +* `X` and `Y` are defined as shared version numbers between all packages. +* The patch level `Z` MAY be incremented individually. +* A PATCH release contains only bug fixes and the version `Z` (`x.y.Z`) MUST be + incremented. A bug fix is an internal change that fixes incorrect behavior + and MUST NOT introduce breaking changes. +* A MINOR release (unlike SemVer) as well as a MAJOR release MAY contain + backwards-incompatible, breaking changes, like API changes and removals and + furthermore bug fixes and new features. + +### Development and nightly releases + +* Development builds (e.g. from a regular CI) MUST be released with a version + number defined as `X.Y.Z.dev+NN`, where `NN` is the git commit hash. +* Nightly releases MUST be released with a version number defined as `X.Y.ZrcYYYYMMDD`. +* The intent is to promote a recent, high quality release candidate to a final + version. + +Binary stamps and tools will continue to report the original release candidate version. + +## Semantics + +The following semantics apply: + +* If the version `X` (`X.y.z`) is increased for one package, the version number + change MUST be adopted by all (other) packages. The same applies for the + version `Y` (`x.Y.Z`). +* If the version `X` or `Y` are changed, `Z` MUST be set `0`. +* After a release, `Y` MUST be increased to ensure precedence of nightly builds. + For example: + * The latest stable release published on November 15th 2024 is versioned as + version `3.0.0`. + * The next nightly builds are released as `3.1.0rc20241116`. + * The next stable release is released as or `3.1.0`. diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 5dd6f01806a1..20ce3f014db0 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -197,6 +197,7 @@ nav: - "developers/general/developer-tips.md" - "developers/general/github-actions.md" - "developers/general/release-management.md" + - "developers/general/versioning-scheme.md" - "developers/general/testing-guide.md" - "Building": - "developers/building/bazel.md"