Skip to content

Commit

Permalink
add bin compat goal
Browse files Browse the repository at this point in the history
fixes #1233
  • Loading branch information
kailuowang authored Sep 7, 2017
1 parent 49f2ecc commit 81e8280
Showing 1 changed file with 27 additions and 0 deletions.
27 changes: 27 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,33 @@ into larger problems.
If you are being harassed, please contact one of [us](#maintainers)
immediately so that we can support you.

### Binary compatibility goal

After `1.0.0` release, we [decided](https://github.com/typelevel/cats/issues/1233)
to use *MAJOR.MINOR.PATCH* [Semantic Versioning 2.0.0](http://semver.org/)
going forward, which is different from the *EPIC.MAJOR.MINOR* schema commonly in
Java and Scala libraries (including the Scala lang).

Cats' strives to provide a solid and stable foundation for an ecosystem of
FP libraries. Thus, we treat maintaining binary compatibility with a high priority.
In semantic versioning, breaking change is **ONLY** allowed between *MAJOR* versions.
We will maintain backward binary compatibility between *PATCH* AND *MINOR* versions.
For example, when we release cats `1.1.0`, it will be backward binary compatible
with the previous `1.0.x` versions. I.E. the new JAR will be a drop-in replacement for
the old one. This is critical when your application has a diamond
dependency on cats - depending on two (or more) libraries that both depend on cats.
If one library upgrades to the new `1.1.0` cats before the other one does, your
application still runs thanks to this backward binary compatibility.

Also worth noting is that according to semantic versioning,
*MINOR* version Y (x.Y.z | x > 0) MUST be incremented
if new, backwards compatible functionality is introduced to the public API.
It MUST be incremented if any public API functionality is marked as deprecated.

Any binary breaking changes will require a *MAJOR* version bump, which we will be very
cautious about. We will also consider using `organization` and package name for major
versioning in the future. But that decision is yet to be made.

### Maintainers

The current maintainers (people who can merge pull requests) are:
Expand Down

0 comments on commit 81e8280

Please sign in to comment.