Stack Version Policy

Major.Minor.Patch

Every stack version is numbered X.Y.Z:

• X: major
• Y: minor
• Z: patch (also called micro)

Pre 1.0

aka, research/experimental releases

We strongly encourage stacks to be released, even when in an unstable state. Building stacks from 'trunk', especially against unstable stacks, can make development very difficult. Regular releases provide a better reference point for building on top of these capabilities.

Although the pre-1.0 version policy is not as strict, the versions and their meanings roughly are:

• 0.1: completely experimental, unreviewed
• 0.2: some review has occurred, and we are migrating this stack to more stable APIs
• 0.3: ready to start including with distributions, though definitely not stable (e.g. web_interface 0.3, pr2_calibration 0.3)
• 0.4-0.8: on stable development cycle towards 1.0 release (aka tick-tock)
• 0.9: 1.0 release candidate

For 0.2 releases, all effort should be made to do preliminary API reviews (based on the API documentation!) of all included packages. These API reviews should be done on an iterative basis as the component gets greater exposure and more is learned about its requirements. Feedback from these API reviews should be used to fill in a roadmap for the stack so that there is shared understanding of how the feedback will be incorporated over time. For more info on review process see APIReviewProcess

Release 1.0

aka, the "M3" process

Reaching 1.0 for a stack usually takes a long development cycle. In our past experience, it often takes a year of experience with a software library, and possibly one or more rewrites, for it to reach 1.0 status. 1.0 is an indicator that we:

• are ready to commit to supporting the APIs in the stack
• have done all necessary review (documentation, user testing) to ensure that the quality of the component is high

A 1.0 stack must have:

• completed API and doc review of all components APIReviewProcess DocReviewProcess

• must only depend on stable components (i.e. any APIs it uses must be maintained under a stable process)
• must have pass through user testing for expected use-case scenarios

Post 1.0

After reaching a 1.0 level stacks released into distros are expected to be stable within a release.

It was previously recommended to follow Odd/Even release cycles, and if a maintainer would like to continue to do so that is fine. However the overhead of extra releases and rebuilding the releases has lead us to not continue this process for core stacks.

Odd/Even process

While it is no more required for core ROS stacks, individual maintainers are free to continue release management using this strategy.

The "odd/even" development cycle mirrors the Linux kernel development process (between 1.0 and the 2.6.x series). We expect distributions to occur roughly at 6 month intervals, which means that the period between two even releases should be < 6 months. Longer development cycles are possible, with the understanding that the distributions will only contain even-number releases.

During an odd cycle, new features are developed, tested, and refined. There is no commitment to stability for these new features during the odd cycle, but there is strong emphasis on early-and-often API review of these new features to ensure that they are stabilized as quickly as possible. There needn't be a formal release announcement to ros-users for each release in this series, but the start of the odd cycle should be prefaced by an announcement that describes the roadmap for the odd cycle. Patch releases in an odd cycle can contain new features and breaking changes to features that were introduced during that odd cycle (minor version).

During an even cycle, the process is the same as the 1.0 release process. All new features from the 1.1 process are fully reviewed and documented, and new use cases have validated their design and documentation. Patch releases during an even cycle can only contain bug fixes -- API changes and new features are not allowed, even if they are backwards compatible.

To given an example:

• common_msgs 1.0: Passed 1.0 process, included in Box Turtle
• common_msgs 1.1.0-1.1.N: new messages are added, reviewed, refined. Releases are made into "Unstable"
• common_msgs 1.2: New messages finalized, documented, and tested. Included in C Turtle.
• common_msgs 1.2.0-1.2.N: Bug fixes only.