From 777173f988f9c0211f7a740bfd3fc6c7444e46cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johan=20Andr=C3=A9n?= Date: Thu, 28 Mar 2019 11:54:39 +0100 Subject: [PATCH] contribution guidelines about wire compatibility (#26619) --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 558c2f59eb..8307abaa34 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -222,6 +222,22 @@ Situations when it may be fine to ignore a MiMa issued warning include: The binary compatibility of the current changes can be checked by running `sbt +mimaReportBinaryIssues`. +## Wire compatibility + +Changes to the binary protocol of remoting, cluster and the cluster tools require great care so that it is possible +to do rolling upgrades. Note that this may include older nodes communicating with a newer node so compatibility +may have to be both ways. + +Since during a rolling upgrade nodes producing the 'new' format and nodes producing the 'old' format coexist, a change can require a two-release process: +the first change is to add a new binary format but still use the old. A second step then starts actually emitting the +new wire format. This ensures users can complete a rolling upgrade first to the intermediate version and then another +rolling upgrade to the next version. + +All wire protocol changes that may concern rolling upgrades should be documented in the +[Rolling Update Changelog](https://doc.akka.io/docs/akka/current/project/rolling-update.html#change-log) +(found in akka-docs/src/main/paradox/project/rolling-update.md) + + ## Pull request requirements For a pull request to be considered at all it has to meet these requirements: