aurora-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject incubator-aurora git commit: Adding thrift API changes document.
Date Fri, 13 Feb 2015 00:37:08 GMT
Repository: incubator-aurora
Updated Branches:
  refs/heads/master 530dad89a -> 253521699

Adding thrift API changes document.

Bugs closed: AURORA-973

Reviewed at


Branch: refs/heads/master
Commit: 25352169914e5f08d29e95761155cc22ef42c903
Parents: 530dad8
Author: Maxim Khutornenko <>
Authored: Thu Feb 12 16:36:56 2015 -0800
Committer: Maxim Khutornenko <>
Committed: Thu Feb 12 16:36:56 2015 -0800

 docs/    |  4 ++-
 docs/ |  4 +++
 docs/          | 50 ++++++++++++++++++++++++++++++++
 3 files changed, 57 insertions(+), 1 deletion(-)
diff --git a/docs/ b/docs/
index e002d90..4ddc77f 100644
--- a/docs/
+++ b/docs/
@@ -86,4 +86,6 @@ a Run configuration:
   is the directory where our example clusters.json is found).
 * You should now be able to run and debug this configuration!
+Making thrift schema changes
+See [this document]( for any thrift related changes.
diff --git a/docs/ b/docs/
index 7f6cc2e..17cfc18 100644
--- a/docs/
+++ b/docs/
@@ -106,3 +106,7 @@ should not be modified directly:
 To upgrade Gradle unpack the new version somewhere, run `/path/to/new/gradle wrapper` in
 repository root and commit the changed files.
+Making thrift schema changes
+See [this document]( for any thrift related changes.
diff --git a/docs/ b/docs/
new file mode 100644
index 0000000..e1f1fbc
--- /dev/null
+++ b/docs/
@@ -0,0 +1,50 @@
+# Thrift API Changes
+## Overview
+Aurora uses [Apache Thrift]( for representing structured data
+client/server RPC protocol as well as for internal data storage. While Thrift is capable
+correctly handling additions and renames of the existing members, field removals must be
+carefully to ensure backwards compatibility and provide predictable deprecation cycle. This
+document describes general guidelines for making Thrift schema changes to the existing fields
+It is highly recommended to go through the
+[Thrift: The Missing Guide]( first to
refresh on
+basic Thrift schema concepts.
+## Checklist
+Every existing Thrift schema modification is unique in its requirements and must be analyzed
+carefully to identify its scope and expected consequences. The following checklist may help
in that
+* Is this a new field/struct? If yes, go ahead
+* Is this a pure field/struct rename without any type/structure change? If yes, go ahead
and rename
+* Anything else, read further to make sure your change is properly planned
+## Deprecation cycle
+Any time a breaking change (e.g.: field replacement or removal) is required, the following
+must be followed:
+### vCurrent
+Change is applied in a way that does not break scheduler/client with this version to
+communicate with scheduler/client from vCurrent-1.
+* Do not remove or rename the old field
+* Add a new field as an eventual replacement of the old one and implement a dual read/write
+anywhere the old field is used
+* Check [storage.thrift](../api/src/main/thrift/org/apache/aurora/gen/storage.thrift) to
see if the
+affected struct is stored in Aurora scheduler storage. If so, you most likely need to backfill
+existing data to ensure both fields are populated eagerly on startup
+See [](../src/main/java/org/apache/aurora/scheduler/storage/
+* Add a deprecation jira ticket into the vCurrent+1 release candidate
+* Add a TODO for the deprecated field mentioning the jira ticket
+### vCurrent+1
+Finalize the change by removing the deprecated fields from the Thrift schema.
+* Drop any dual read/write routines added in the previous version
+* Remove the deprecated Thrift field
+## Testing
+It's always advisable to test your changes in the local vagrant environment to build more
+confidence that you change is backwards compatible. It's easy to simulate different
+client/scheduler versions by playing with `aurorabuild` command. See [this document](
+for more.

View raw message