Question: Minor vs Patch Increment?

[benjchristensen]

I'd like to get opinions on what justifies incrementing the minor version (1.0.x -> 1.1.x) as opposed to the patch version.

Technically the minor version should increment when new functionality is added. In RxJava though were it's about a long list of operators, that could mean we increment minor versions quite often. Also, should it increment when they are added as @Experimental or @Beta or only once they become stable?

Examples:

• Beta & Experimental Annotations #1905 Beta & Experimental Annotations
• Experimental: onBackpressureBlock #1907 Experimental: onBackpressureBlock
• Experimental onBackpressureBufferWithCapacity #1916 Experimental onBackpressureBufferWithCapacity

Currently we have the definition of minor and patch as this:

---

Minor 1.x increments (such as 1.1, 1.2, etc) will occur when non-trivial new functionality is added or significant enhancements or bug fixes occur that may have behavioral changes that may affect some edge cases (such as dependence on behavior resulting from a bug). An example of an enhancement that would classify as this is adding reactive pull backpressure support to an operator that previously did not support it. This should be backwards compatible but does behave differently.

Patch 1.x.y increments (such as 1.0.0 -> 1.0.1, 1.3.1 -> 1.3.2, etc) will occur for bug fixes and trivial functionality (like adding a method overload). New functionality marked with an @Beta or @Experimental annotation can also be added in patch releases to allow rapid exploration and iteration of unstable new functionality.

---

Should we allow additional operators and functionality on patch versions if we deem them trivial (a subjective decision) and only increment the minor version when we subjectively determine significant additions? This would mean we have low minor versions and high patch versions, such as 1.0.17, 1.1.20, etc.

Or should we liberally increment the minor version anytime something is added to the APIs? This would mean high minor versions and low patch versions, such as 1.15.1, 1.27.0, 1.45.3, etc.

I would appreciate guidance on what is expected or preferred.

[benjchristensen]

/cc @headinthebox @akarnokd @zsxwing @daschl @JakeWharton @mttkay

[benjchristensen]

The http://semver.org site argues for incrementing the minor version liberally as per this guidance:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Based on this the pull requests we have right now would already require us to move to 1.1.0 for the next release. Is that correct?

[JakeWharton]

Currently we have the definition of minor and patch as this

I tend to follow almost exactly what was defined under the above title. You also later mention the subjective aspect in making the minor bump which I also employ in versioning.

I bump the minor versions when there's an addition of a new API that enables new functionality in interesting ways (subjective) or there's simply a large grouping of small, incremental changes which represent a step forward in the completeness, applicability, or stability of the library (also subjective).

The promotion of @Beta and/or @Experimental APIs to stable seems like something that both should be batched together and represents the latter of the aforementioned subjective reasons to bump the minor version.

With regard to pure semantic versioning, I don't like the cognitive overhead that comes with the rapid incrementing. Trivial, non-bugfix changes become normalized alongside the more significant, additive changes whose importance is thus diminished. You are either forced into paying very close attention to every minor release to see if there's anything worth looking at or you simply become numb to the changes and update less frequently and/or ignore them.

[benjchristensen]

Thanks @JakeWharton, that is exactly the type of feedback I was hoping for, and better yet it matches my personal perspective.

I don't like the cognitive overhead that comes with the rapid incrementing

I completely agree with this and your further reasoning which matches my dislike of pure semantic versioning.

I'm going to stick to our already defined minor/patch model and optimize for making minor version bumps meaningful and something people should pay attention to.

[daschl]

Here is my take on this, and it I guess overlaps quite a lot with what you both have been writing here.

As a library user, I expect things keep working when I go to the latest patch version. If this one includes experimental additional features, as long as I don't have to change something in my app to keep it working its fine.

As a library maintainer, I can feel the tension between shipping new things and increasing minor all the time. It requires thorough planning and a solid roadmap going forward, otherwise you end up with lots of minor bumps and, in my experience, users tend to upgrade more slowly to minors instead of patch releases. I've seen environments where minors are not allowed without extra QE passes but patch releases are allowed to be deployed into prod.

At Couchbase we're not trying to do more than one minor release per quarter (at max) to find a balance between shipping new features but also giving users a chance to upgrade, but also not put too much maintenance cherry-picking on us if we need to support tons of different minor branches. So if its a smaller experimental change we get it into a patch release, mark it as experimental, get feedback from users and then promote it to stable with a successive minor release.

As a side note, sometimes those experimental changes require, even if the surface API doesn't change, large changes in the codebase and then I refrain from doing it in a patch release because the chance it brings up issues is much more likely.

One good thing, since RxJava has no dependencies, is how to handle dependency bumps on patch and minor versions. This is a whole different topic and probably not worth discussing here.

[mttkay]

One thing I would like to emphasize from semver:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

I very much think we're still in this phase, and will be for a while. While in pre-release stage, I think we should liberally bump the minor version. In general I would rather bump minor even if the impact is small as opposed to bumping patch when the impact is high. This is also to shield developers from breaking changes and to give us breathing room to move quickly.

On the road to stability I'm fine with what you suggest though.

[benjchristensen]

We addressed this by adding @Experimental and @Beta annotations. All development happens in patch releases. Minor releases are for promoting public APIs from @Experimental and @Beta to stable.