Skip to content

Commit fb65d66

Browse files
authored
Clarify interface stability (ros2#691)
* Clarify interface stability * Update Developer-Guide.rst * Update Developer-Guide.rst * Update Developer-Guide.rst * Add line breaks between sentences * Rephrase "initial development" phrasing
1 parent 5b28611 commit fb65d66

File tree

1 file changed

+9
-4
lines changed

1 file changed

+9
-4
lines changed

source/Contributing/Developer-Guide.rst

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,12 +44,17 @@ We will use the `Semantic Versioning guidelines <http://semver.org/>`__ (``semve
4444

4545
We will also adhere to some ROS-specific rules built on top of ``semver's`` full meaning:
4646

47-
* Major version increments (i.e. breaking changes) will not be made within a released distribution.
48-
* In addition to avoiding major API increments to ensure API stability according to ``semver``, we will be ABI (and therefore API) stable within a ROS distribution.
47+
* Major version increments (i.e. breaking changes) should not be made within a released ROS distribution.
4948

50-
* We will not allow patch (bug-fixes) and minor (non-breaking) version increments to affect API and ABI within a released distribution.
49+
* Patch (interface-preserving) and minor (non-breaking) version increments do not break compatibility, so these sorts of changes *are* allowed within a release.
5150

52-
* `Unlike semver <https://semver.org/#spec-item-4>`_, we guarantee API/ABI compatibility within Dashing and Eloquent despite both distributions being under version ``1.0.0``.
51+
* Major ROS releases are the best time to release breaking changes.
52+
If a core package needs multiple breaking changes, they should be merged into their integration branch (e.g. master) to allow catching problems in CI quickly, but released together to reduce the number of major releases for ROS users.
53+
54+
* For compiled code, the ABI is considered part of the public interface.
55+
Any change that requires recompiling dependent code is considered major (breaking).
56+
57+
* We enforce API stability for core packages in Dashing and Eloquent even though their major version components are ``0``, despite `SemVer's specification <https://semver.org/#spec-item-4>`_ regarding initial development.
5358

5459
* Subsequently, packages should strive to reach a mature state and increase to version ``1.0.0`` so to match ``semver's`` specifications.
5560

0 commit comments

Comments
 (0)