From 3192c34dc4151d52d04ba8a60cbf1d2e63f0e4ad Mon Sep 17 00:00:00 2001 From: Enno <458526+ennru@users.noreply.github.com> Date: Fri, 28 Jun 2019 13:40:17 +0200 Subject: [PATCH] Describe versioning rules in docs (#1789) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Martynas Mickevičius --- docs/src/main/paradox/kinesis.md | 2 +- docs/src/main/paradox/other-docs/index.md | 1 + .../src/main/paradox/other-docs/versioning.md | 62 +++++++++++++++++++ docs/src/main/paradox/release-notes/1.0.x.md | 6 +- docs/src/main/paradox/release-notes/index.md | 2 + docs/src/main/paradox/solr.md | 2 - project/plugins.sbt | 2 +- 7 files changed, 71 insertions(+), 6 deletions(-) create mode 100644 docs/src/main/paradox/other-docs/versioning.md diff --git a/docs/src/main/paradox/kinesis.md b/docs/src/main/paradox/kinesis.md index 621914c026..19d0e9f987 100644 --- a/docs/src/main/paradox/kinesis.md +++ b/docs/src/main/paradox/kinesis.md @@ -153,7 +153,7 @@ Scala Java : @@snip [snip](/kinesis/src/test/java/docs/javadsl/KinesisFirehoseSnippets.java) { #init-client } -### Kinesis Put via Flow or as Sink +### Kinesis Firehose Put via Flow or as Sink The @scala[@scaladoc[KinesisFirehoseFlow](akka.stream.alpakka.kinesisfirehose.scaladsl.KinesisFirehoseFlow$) (or @scaladoc[KinesisFirehoseSink](akka.stream.alpakka.kinesisfirehose.scaladsl.KinesisFirehoseSink$))] diff --git a/docs/src/main/paradox/other-docs/index.md b/docs/src/main/paradox/other-docs/index.md index 4d4c3f7aa3..a129d5e9af 100644 --- a/docs/src/main/paradox/other-docs/index.md +++ b/docs/src/main/paradox/other-docs/index.md @@ -5,6 +5,7 @@ @@@ index * [Webinars Presentations and Articles](webinars-presentations-articles.md) +* [versioning](versioning.md) * [Snapshots](snapshots.md) * [Reference connector](../reference.md) diff --git a/docs/src/main/paradox/other-docs/versioning.md b/docs/src/main/paradox/other-docs/versioning.md new file mode 100644 index 0000000000..297544c130 --- /dev/null +++ b/docs/src/main/paradox/other-docs/versioning.md @@ -0,0 +1,62 @@ +# Versioning + +Alpakka uses the versioning scheme `major.minor.patch` (just as the rest of the Akka family of projects). The Akka family diverges a bit from Semantic Versioning in that new, compatible functionality is added in patch releases. + +@@@ note + +As all Alpakka modules (excluding Alpakka Kafka) share a single version number, modules often don't contain any notable changes even though the version number has changed significantly. + +@@@ + +Alpakka publishes + +* regular releases to [Maven Central](https://search.maven.org/search?q=g:com.lightbend.akka%20akka-stream-) +* milestone and release candidates (of major versions) to Maven Central +* @ref:[snapshots](snapshots.md) to [Bintray](https://bintray.com/akka/snapshots/alpakka) + +### Compatibility + +Our ambition is to evolve Alpakka modules without breaking users’ code. There are two sides to that: One is **binary-compatibility** which effectively means you can replace just the jar with a later version’s jar in your installation and everything will work. This becomes extremely important as soon as you use other libraries that rely on the same jar. They will continue to work without recompilation. The other is **source-compatibility** which, when upgrading to a later minor version, would not require any code changes. Akka and Alpakka strive for binary-compatibility and source-compatibility, but we do not guarantee source-compatibility. + +Read about the details in the @extref:[Akka documentation](akka:common/binary-compatibility-rules.html). + + +### Mixing versions + +**All connectors of Alpakka can be used independently**, you may mix Alpakka versions for different libraries. Some may share dependencies which could be incompatible, though (eg. Alpakka connectors to AWS services). + + +### Akka versions + +With Akka though, it is important to be strictly using one version (never blend eg. `akka-actor 2.5.21` and `akka-stream 2.5.12`), and do not use an Akka version lower than the one the Alpakka dependency requires (sometimes Alpakka modules depend on features of the latest Akka release). + +Alpakka’s Akka and Akka HTTP dependencies are upgraded only if that version brings features leveraged by Alpakka or important fixes. As Akka itself is binary-compatible, the Akka version may be upgraded with an Alpakka patch release. + +@@@ note + +Users are recommended to upgrade to the latest Akka version later than the one required by Alpakka at their convenience. + +@@@ + + +### Scala versions + +The "Project information" section for every connector states which versions of Scala it is compiled with. + + +### Third-party dependencies + +Alpakka depends heavily on third-party (non-Akka) libraries to integrate with other technologies via their client APIs. To keep up with the development within the technologies Alpakka integrates with, Alpakka connectors need to upgrade the client libraries regularly. + +Code using Alpakka will in many cases even make direct use of the client library and thus depend directly on the version Alpakka pulls into the project. Not all libraries apply the same rules for binary- and source-compatibility and it is very hard to track all of those rules. + +For this reason any library upgrade must be made with care to not break user code in unexpected ways. + +* An upgrade to a *patch release of a library* may be part of an Alpakka patch release (if nothing indicates the library upgrade would break user code). +* An upgrade to a *minor release of a library* may be part of a minor Alpakka release (if nothing indicates the library upgrade would break user code). +* For *major release upgrades of a library*, the Alpakka team will decide case-by-case if the upgrade motivates an upgrade of the Alpakka major version. + * For source incompatible library upgrades, Alpakka will do a major version upgrade. + * If the library indicates it is considered binary-compatible, Alpakka may upgrade within a minor release. + +If a project needs to rely on the binary-compatibility rules to just replace the Alpakka dependency, care must be taken to replace any upgraded third-party library to the version used by Alpakka at the same time. This should normally work when overriding an Alpakka dependency of a library in a build dependency definition, as the build tool will do all the necessary evictions as long as evicted libraries are backwards binary-compatible. + diff --git a/docs/src/main/paradox/release-notes/1.0.x.md b/docs/src/main/paradox/release-notes/1.0.x.md index 667e257c86..be1b89d614 100644 --- a/docs/src/main/paradox/release-notes/1.0.x.md +++ b/docs/src/main/paradox/release-notes/1.0.x.md @@ -1,5 +1,7 @@ # Alpakka 1.0.x +To understand the forces on version numbers, read about @ref:[Alpakka's versioning scheme](../other-docs/versioning.md). + ## 1.0.2 Released 2019-05-25 @@ -13,7 +15,7 @@ This release fixes a bug in the CSV parser which was introduced in 1.0.1 and mak **See [changes per module](#changes-per-module)** -## Contributors +## Contributors in 1.0.2 | Author | Commits | Lines added | Lines removed | | ------ | ------- | ----------- | ------------- | @@ -44,7 +46,7 @@ Released 2019-05-16 **See [changes per module](#changes-per-module)** -## Contributors +## Contributors in 1.0.1 | Author | Commits | Lines added | Lines removed | | ------ | ------- | ----------- | ------------- | diff --git a/docs/src/main/paradox/release-notes/index.md b/docs/src/main/paradox/release-notes/index.md index 8f3a4fe9a1..7656822a4e 100644 --- a/docs/src/main/paradox/release-notes/index.md +++ b/docs/src/main/paradox/release-notes/index.md @@ -1,5 +1,7 @@ # Release Notes +To understand the forces on version numbers, read about @ref:[Alpakka's versioning scheme](../other-docs/versioning.md). + @@toc { depth=2 } @@@ index diff --git a/docs/src/main/paradox/solr.md b/docs/src/main/paradox/solr.md index 804481f3d6..cd8187fcbe 100644 --- a/docs/src/main/paradox/solr.md +++ b/docs/src/main/paradox/solr.md @@ -101,8 +101,6 @@ Java : @@snip [snip](/solr/src/test/java/docs/javadsl/SolrTest.java) { #define-class } -#### Writing `SolrInputDocument`s - Use `SolrSink.documents`, `SolrFlow.documents` or `SolrFlow.documentsWithPassThrough` to stream `SolrInputDocument`s to Solr. A `SolrClient` must be provided to diff --git a/project/plugins.sbt b/project/plugins.sbt index e2a2d0d0f8..9fb366635b 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -3,7 +3,7 @@ addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.0.1") addSbtPlugin("com.dwijnand" % "sbt-dynver" % "4.0.0") addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-dependencies" % "0.1") addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-project-info" % "1.1.2") -addSbtPlugin("com.lightbend.akka" % "sbt-paradox-akka" % "0.18") +addSbtPlugin("com.lightbend.akka" % "sbt-paradox-akka" % "0.20") addSbtPlugin("com.lightbend.sbt" % "sbt-publish-rsync" % "0.1") addSbtPlugin("com.eed3si9n" % "sbt-unidoc" % "0.4.2") addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "2.1.0")