Releases
Versioning
maliput
packages will adhere to semantic versioning and
will follow the ROS2 Versioning guidelines .
IMPORTANT: maliput
is still under actively development so semantic versioning is not yet strictly followed for the 1.X.Y versions.
Releases
Named major releases
Significant releases of Maliput packages will be named. The names will be chosen based on famous roads and will be alphabetically sorted. Significant releases will be created on demand.
Major release output
Every new major release will provide:
Updated
maliput_rolling.repos
file when appropriate (new major release, update to latest minor release or patch release).New
maliput_<name>.repos
file.Binaries distributed via ROS Build Farm.
How to release?
There are different steps to follow based on the type of release you want to create.
Make a new major maliput
workspace release
Choose a name that is next in the alphabet relative to the previous major release.
Prepare the workspace by pinning all dependencies and downstream packages to their target branches or tags.
Build and test the workspace with all packages pointing to their pinned versions.
Update
maliput_rolling.repos
file in repos_index under the appropriate ROS2 distro folder.Create a new
maliput_<name>.repos
file in repos_index under the appropriate ROS2 distro folder.Rely on bloom tools for the releasing process.
Create a new package major release
Prepare the workspace by pinning all dependencies and downstream packages to their target branches or tags.
Prepare the release branch:
Update the
CHANGELOG.rst
andpackage.xml
files via a PR targetingmain
.From
main
branch, create a new branch calledrelease/major.minor.x
.x
is not a placeholder, it is the literal x because this branch will contain all the potential future patch releases in the series ofmajor.minor.0
,major.minor.1
and so on (e.g. 1.3.0, 1.3.1, 1.3.2, etc.). A tag will be used to name the specific commit in the branch.Run all tests. If you encounter any problem, send PRs to fix them targeting
main
branch. Merge those commits intorelease/major.minor.x
.
Push the branch.
Make a tag with the appropriate version number:
release/major.minor.0
.Push the tag.
Create a PR to repos_index and update
maliput_rolling.repos
to indicate the branch namerelease/major.minor.x
as the latest package version.Rely on bloom tools for the releasing process.
Create a new package minor release
Prepare the workspace by pinning all dependencies and downstream packages to their target branches or tags.
Prepare the release branch:
From the tip of
release/major.[minor - 1].x
, create a new branch calledrelease/major.minor.x
.Push the branch
release/major.minor.x
.Cherry-pick commits as needed from
main
and include them intorelease/major.minor.x
via PRs. Alternatively, create feature branches whose PRs targetrelease/major.minor.x
.Update the
CHANGELOG.rst
andpackage.xml
via a PR targetingrelease/major.minor.x
.Run all tests. If you encounter any problem, send PRs to fix them targeting
release/major.minor.x
branch.
Make a tag with the appropriate version number:
release/major.minor.0
.Push the tag.
When the
major
andminor
version numbers are the greatest: create a PR to repos_index and updatemaliput_rolling.repos
to indicate the branch namerelease/major.minor.x
as the latest package version.Consider updating the affected named
maliput
workspace releases.Rely on bloom tools for the releasing process.
Create a new package patch release
Prepare the workspace by pinning all dependencies and downstream packages to their target branches or tags.
Prepare the release branch:
Cherry-pick commits as needed from
main
and include them intorelease/major.minor.x
via PRs. Alternatively, create feature branches whose PRs targetrelease/major.minor.x
.Update the
CHANGELOG.rst
andpackage.xml
via a PR targetingrelease/major.minor.x
.Run all tests. If you encounter any problem, send PRs to fix them targeting
release/major.minor.x
branch.
Make a tag with the appropriate version number:
release/major.minor.patch
.Push the tag.
Consider updating the affected named
maliput
workspace release.Rely on bloom tools for the releasing process.
Publishing releases
Every time a new release occurs, maintainers are required to publish the release to various places:
Github page
ROS Build Farm
Bazel Central Registry
Python Package Index
Rust Crate Registry
The following sections explain the process maintainers must follow to effectively publish releases.
Github Page
Every time a new tag is pushed, a specific Github Release page is created thanks to a Github Action. For example, look at maliput/.github/workflows/release.yml which essentially does the following:
Archives the repository at the release tag commit version.
Creates a new entry with it in the releases page (e.g. maliput release page).
NOTE: it is recommended to push the tag once the release PR has been merged to false release bundles.
ROS Build Farm
TODO(https://github.com/maliput/maliput_documentation/issues/156)
Bazel Central Registry
The Github maliput organization hosts a fork of bazel-central-registry. Upon pushing the tag,
and the release page creation, a PR with the bazel configuration files is created to register a new release in BCR (from our fork to upstream).
Right now, only maliput and maliput_malidrive are published to BCR, but more could be published as requested.
Every published package has a hidden folder called .bcr
with the BCR configuration.
See maliput’s for an example.
Process:
Push the tag to the repository.
The github automation will create a PR from the forked bazel-central-registry to upstream.
Make sure CI pipeline is green.
Request the registered maintainer to approve the PR.
Ping bazel-central-registry maintainers for a review and merge.
Python Package Index
At the moment, both maliput and maliput_malidrive are distributed via PyPI. To publish a new version, use the Github Action pipeline to generate the corresponding wheel.
Process:
Once a tag has been pushed with the release version, kick off the workflow from that tag.
Download the generated asset once the pipeline finishes.
Unzip the asset and you should end up with a
.whl
file that needs to be pushed to PyPI.Log in to PyPI and generate an API Token for the project to publish to.
Install
twine
:pip install twine
.Publish the wheel using
twine
:twine upload your_wheel_file_name.whl
. Use your username and previously generated API Token.
Consider removing your API Token after finishing with this process and create one for each package to increase security.
Rust Crate Registry
Using cargo
you can create crates and publish them directly to crates.io. To do so:
Prepare a release, check, build and test the packages to release.
1cargo check --workspace --all-targets
2cargo build --workspace --all-targets
3cargo test --workspace --all-targets
Obtain a token at your user settings in crates.io
Login using the token using cargo CLI:
1cargo login
Try to evaluate the publish to be released, e.g. with
maliput-sdk
:
1cargo publish --dry-run --verbose --package maliput-sdk
When everything goes well, proceed to release it:
1cargo publish --verbose --package maliput-sdk
You should see it in the respective page at crates.io.