From b9dc8889ed3d95382779e8914dff8147bc2ceb65 Mon Sep 17 00:00:00 2001 From: Enno <458526+ennru@users.noreply.github.com> Date: Fri, 14 Jun 2019 15:25:27 +0200 Subject: [PATCH 1/2] Explain MiMa use for contributors --- .travis.yml | 2 +- CONTRIBUTING.md | 26 ++++++++++++++++++++++++++ 2 files changed, 27 insertions(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 9bdaee153d..08bc5bdb44 100644 --- a/.travis.yml +++ b/.travis.yml @@ -28,7 +28,7 @@ jobs: - env: CMD="docs/paradox" name: "Create site with Paradox" - env: CMD="mimaReportBinaryIssues" - name: "Check binary compatibility" + name: "Check binary compatibility (MiMa)" - stage: test env: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 631aa48f8a..76b4c11e14 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,6 +39,32 @@ In case of questions about the contribution process or for discussion of specifi We've collected a few notes on how we would like Alpakka modules to be designed based on what has evolved so far. Please have a look at our [contributor advice](contributor-advice.md). + +## Binary compatibility (MiMa) + +Binary compatibility rules and guarantees are described in depth in the [Binary Compatibility Rules +](https://doc.akka.io/docs/akka/snapshot/common/binary-compatibility-rules.html) section of the Akka documentation. + +Akka projects use MiMa (which originally was called [Lightbend Migration Manager](https://github.com/lightbend/mima)) to +validate binary compatibility of incoming pull requests. In the Travis build step "Check binary compatibility", you may see +an error like this: + +``` +[info] akka-stream: found 1 potential binary incompatibilities while checking against com.typesafe.akka:akka-stream_2.12:2.4.2 (filtered 222) +[error] * method foldAsync(java.lang.Object,scala.Function2)akka.stream.scaladsl.FlowOps in trait akka.stream.scaladsl.FlowOps is present only in current version +[error] filter with: ProblemFilters.exclude[ReversedMissingMethodProblem]("akka.stream.scaladsl.FlowOps.foldAsync") +``` + +In such situations it's good to consult with a core team member if the violation can be safely ignored (by adding the above snippet to `/src/main/mima-filters/.backwards.excludes`), or if it would indeed break binary compatibility. + +Situations when it may be fine to ignore a MiMa issued warning include: + +- if it is concerning internal classes in package `impl` or `internal` + - add eg. `1.0.x.backwards.excludes` with `ProblemFilters.exclude[Problem]("akka.stream.alpakka..impl.*")` to ignore all internal changes +- if it is touching anything marked as `@InternalApi` + +The binary compatibility of the current changes can be checked by running `mimaReportBinaryIssues` in sbt. + ## Pull Request Requirements For a Pull Request to be considered at all it has to meet these requirements: From a7501ef2c6c5241cf0d3619688e9f90158cad562 Mon Sep 17 00:00:00 2001 From: Enno <458526+ennru@users.noreply.github.com> Date: Mon, 17 Jun 2019 11:20:47 +0200 Subject: [PATCH 2/2] Move link to MiMa MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Martynas Mickevičius --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 76b4c11e14..9ca4c896b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,7 +45,7 @@ Please have a look at our [contributor advice](contributor-advice.md). Binary compatibility rules and guarantees are described in depth in the [Binary Compatibility Rules ](https://doc.akka.io/docs/akka/snapshot/common/binary-compatibility-rules.html) section of the Akka documentation. -Akka projects use MiMa (which originally was called [Lightbend Migration Manager](https://github.com/lightbend/mima)) to +Akka projects use [MiMa](https://github.com/lightbend/mima) (which originally was called Lightbend Migration Manager) to validate binary compatibility of incoming pull requests. In the Travis build step "Check binary compatibility", you may see an error like this: