aurora-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
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 https://reviews.apache.org/r/29117/


Project: http://git-wip-us.apache.org/repos/asf/incubator-aurora/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-aurora/commit/25352169
Tree: http://git-wip-us.apache.org/repos/asf/incubator-aurora/tree/25352169
Diff: http://git-wip-us.apache.org/repos/asf/incubator-aurora/diff/25352169

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

----------------------------------------------------------------------
 docs/developing-aurora-client.md    |  4 ++-
 docs/developing-aurora-scheduler.md |  4 +++
 docs/thrift-deprecation.md          | 50 ++++++++++++++++++++++++++++++++
 3 files changed, 57 insertions(+), 1 deletion(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-aurora/blob/25352169/docs/developing-aurora-client.md
----------------------------------------------------------------------
diff --git a/docs/developing-aurora-client.md b/docs/developing-aurora-client.md
index e002d90..4ddc77f 100644
--- a/docs/developing-aurora-client.md
+++ b/docs/developing-aurora-client.md
@@ -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](thrift-deprecation.md) for any thrift related changes.

http://git-wip-us.apache.org/repos/asf/incubator-aurora/blob/25352169/docs/developing-aurora-scheduler.md
----------------------------------------------------------------------
diff --git a/docs/developing-aurora-scheduler.md b/docs/developing-aurora-scheduler.md
index 7f6cc2e..17cfc18 100644
--- a/docs/developing-aurora-scheduler.md
+++ b/docs/developing-aurora-scheduler.md
@@ -106,3 +106,7 @@ should not be modified directly:
 
 To upgrade Gradle unpack the new version somewhere, run `/path/to/new/gradle wrapper` in
the
 repository root and commit the changed files.
+
+Making thrift schema changes
+============================
+See [this document](thrift-deprecation.md) for any thrift related changes.

http://git-wip-us.apache.org/repos/asf/incubator-aurora/blob/25352169/docs/thrift-deprecation.md
----------------------------------------------------------------------
diff --git a/docs/thrift-deprecation.md b/docs/thrift-deprecation.md
new file mode 100644
index 0000000..e1f1fbc
--- /dev/null
+++ b/docs/thrift-deprecation.md
@@ -0,0 +1,50 @@
+# Thrift API Changes
+
+## Overview
+Aurora uses [Apache Thrift](https://thrift.apache.org/) for representing structured data
in
+client/server RPC protocol as well as for internal data storage. While Thrift is capable
of
+correctly handling additions and renames of the existing members, field removals must be
done
+carefully to ensure backwards compatibility and provide predictable deprecation cycle. This
+document describes general guidelines for making Thrift schema changes to the existing fields
in
+[api.thrift](../api/src/main/thrift/org/apache/aurora/gen/api.thrift).
+
+It is highly recommended to go through the
+[Thrift: The Missing Guide](http://diwakergupta.github.io/thrift-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
+analysis:
+* 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
cycle
+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 [StorageBackfill.java](../src/main/java/org/apache/aurora/scheduler/storage/StorageBackfill.java)
+* 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](vagrant.md)
+for more.
+


Mime
View raw message