Ottomata has uploaded a new change for review.

Change subject: Add Versioning documentation to README

Add Versioning documentation to README

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

  git pull ssh:// 

diff --git a/jsonschema/mediawiki/ b/jsonschema/mediawiki/
index 1271f4a..c57ecba 100644
--- a/jsonschema/mediawiki/
+++ b/jsonschema/mediawiki/
@@ -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
+## 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 coordinatoed.
+Ideally, each new schema version would be represented by a bump in file version
+number.  A new version of `mediawiki/revsion/create/1.yaml` would go in
+`mediawiki/revision/create/2.yaml`.  However, at the time of this writing
+(2016-09), we have not every 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
To unsubscribe, visit

Gerrit-MessageType: newchange
Gerrit-Change-Id: Ieb7716b2116e5f9ccc5a32ea57c9d38f6e8ee358
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/event-schemas
Gerrit-Branch: master
Gerrit-Owner: Ottomata <>

MediaWiki-commits mailing list

Reply via email to