Release Process#
This document provides a high-level overview of the VTK release cycle and associated release process.
Overview#
We aim to release a new version of VTK every six months. However, we recognize that this schedule is flexible. The project is funded and developed by many different groups, each of which works towards their own particular sets of features.
VTK releases are named with a Major.Minor.Patch
scheme.
Branching Scheme#
The overall release history resembles a skinny tree. Development proceeds along
the master
branch, consisting of topic branches that start from and are merged
into master
. Every so often, a release is tagged and branched from it.
In general, no work takes place on the release
branch, other than the handful
of important patches that make up occasional patch releases.
Hint
Steps for contributing changes specific to the release
branch are documented in
Create a Topic.
On the master
branch, bug fixes and new features are continuously
developed. At release time, the focus temporarily shifts to producing
a library that is as stable and robust as possible.
Steps#
The process for cutting releases is as follows:
Announce upcoming release
A few weeks before the intended
release
branch, announce on VTK Discourse that a new release is coming. This alerts developers to avoid making drastic changes that might delay the release and gives them a chance to push important and nearly completed features in time for the release. For example, see this post.Polish the dashboards and bug tracker by addressing outstanding issue and coordinate effort with relevant developers.
Persistent compilation and regression test problems are fixed. Serious outstanding bugs are fixed.
Create a new issue titled
Release X.Y.Z[rcN]
based of the new-release template.Important
Specific steps to create eiter the candidate or the official release are found in the newly created issue.
Perform the release candidate cycle
Tag the release branch and create and publish release candidate artifacts and change summaries.
Announce the release candidate and request feedback from the community, especially third-party packagers.
Hint
Bug reports should be entered into the bug tracker with the upcoming release number as the milestone.
If the community reports bugs, classify them in the bug tracker and ensure they are fixed.
Only serious bugs and regressions need to be fixed before the release. New features and minor problems should be merged into
master
as usual.Patches for the release branch should start from the release branch, be submitted through GitLab, and then merged into
master
. Once fully tested there, the branch can be merged into the release branch.When the selected issues are fixed in the release branch, tag the tip of the release branch and release it as the next candidate, then the cycle continues.
Distribution specific patches can accumulate over time. Consider reviewing the following distribution specific pages to identify potential fixes and improvements that could be integrated in VTK itself:
Package the official release
The official VTK package consists of tar balls and ZIP files of the source, Python Wheels, Doxygen documentation, and regression test data, all at the tag point.
Volunteer third-party packagers create binary packages from the official release for various platforms, so their input is especially valuable during the release cycle.
The release manager also compiles release notes for the official release announcement. Release notes are compiled from various standardized topic documents added to the
Documentation/release/dev
folder while features or issues are fixed. The aggregation of these topic files is done manually and results in the creation of a file namedDocumentation/release/X.Y.md
for the current release.
GitLab and Releases#
GitLab milestones are used for keeping track of branches for the release. They allow keeping track of issues and merge requests which should be “done” for the milestone to be considered complete.
For each release (including release candidates), a milestone is created with a plausible due date. The milestone page allows for an easy overview of branches which need wrangling for a release.
Merge Requests#
Merge requests which need to be rebased onto the relevant release branch
should be marked with the needs-rebase-for-release
tag and commented on how
the branch can be rebased properly:
This branch is marked for a release, but includes other commits in
`master`. Please either rebase the branch on top of the release branch and
remove the `needs-rebase-for-release` tag from the merge request:
```sh
$ git rebase --onto=origin/release origin/master $branch_name
$ git gitlab-push -f
```
or, if there are conflicts when using a single branch, open a new branch
and open a merge request against the `release` branch:
```sh
$ git checkout -b ${branch_name}-release $branch_name
$ git rebase --onto=origin/release origin/master ${branch_name}-release
$ git gitlab-push
```
Thanks!
Wrangling Branches#
Branches may be wrangled using the filters in the merge request page. Replace
$release
at the end with the relevant milestone name:
https://gitlab.kitware.com/vtk/vtk/-/merge_requests?state=all&milestone_title=$release
The following states of a merge request indicate where they are in the flow:
open for
master
: get intomaster
firstopen for
release
: ensure it is already inmaster
open with
needs-rebase-for-release
tag: wait for contributor to rebase properly; ping if necessaryMERGED
: merge intorelease
There is currently no good way of marking a branch that went towards master
is also in release
already since tags cannot be added to closed merge
requests. Suggestions welcome :) .