Ppchelko has submitted this change and it was merged.

Change subject: Add Versioning documentation to README
......................................................................


Add Versioning documentation to README

Change-Id: Ieb7716b2116e5f9ccc5a32ea57c9d38f6e8ee358
---
M jsonschema/mediawiki/README.md
1 file changed, 18 insertions(+), 0 deletions(-)

Approvals:
  Ppchelko: Verified; Looks good to me, approved



diff --git a/jsonschema/mediawiki/README.md b/jsonschema/mediawiki/README.md
index 1271f4a..b37cb90 100644
--- a/jsonschema/mediawiki/README.md
+++ b/jsonschema/mediawiki/README.md
@@ -28,3 +28,21 @@
 `revision_create`) should be considered deprecated.  Analytics and Services are
 working together to switch over uses of these schemas to the new entity-first
 ones.
+
+## Versioning
+New schema versions should be 100% backwards compatible.  That is, they should
+only add new optional fields.  They should never remove or rename fields, and
+they should never add new required fields.  This allows producer and consumer
+code to continue to work with older versions of schemas, so deployments that
+alter use of schema versions do not have to be coordinated.
+
+Ideally, each new schema version would be represented by a bump in file version
+number.  A new version of `mediawiki/revision/create/1.yaml` would go in
+`mediawiki/revision/create/2.yaml`.  However, at the time of this writing
+(2016-09), we have not ever created a new schema version in a new file, and
+have instead altered the original schema versions with new git commits.
+While not ideal, this is 'ok' for now, especially if we are 100% sure that
+the schema change is backwards compatible, AND that we only have one producer
+of this data: MediaWiki.  This may change in the future.  If and when it does,
+we will have to be more strict about using new files for new schema versions.
+

-- 
To view, visit https://gerrit.wikimedia.org/r/312309
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: Ieb7716b2116e5f9ccc5a32ea57c9d38f6e8ee358
Gerrit-PatchSet: 3
Gerrit-Project: mediawiki/event-schemas
Gerrit-Branch: master
Gerrit-Owner: Ottomata <o...@wikimedia.org>
Gerrit-Reviewer: Ppchelko <ppche...@wikimedia.org>

_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits

Reply via email to