From d4db1f1217841505445b317d8c980fe706d6ef52 Mon Sep 17 00:00:00 2001
From: adriancole <adrian.f.cole@gmail.com>
Date: Mon, 14 Dec 2020 08:37:49 +0800
Subject: [PATCH 1/2] Clarifies text in schema extension example

While correct, the schema extension example could be misinterpreted due
to vocabulary used. For example, a new reader who missed the implicit
zero based versioning, could misunderstand how version 1 appeared in
updates.

This change walks through the thinking behind the example, so that
readers have less cognitive break even if they misread the spec.
---
 v2-0-RC3/doc/05SchemaExtensionMechanism.md | 32 ++++++++++++++++++----
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/v2-0-RC3/doc/05SchemaExtensionMechanism.md b/v2-0-RC3/doc/05SchemaExtensionMechanism.md
index 775f27b..a7411ca 100644
--- a/v2-0-RC3/doc/05SchemaExtensionMechanism.md
+++ b/v2-0-RC3/doc/05SchemaExtensionMechanism.md
@@ -122,13 +122,18 @@ If the *received version is less than the decoder's version* (that is, the produ
 
 ## Message schema extension example
 
-Initial version of a message schema
+The following example walks through changes to a schema to reinforce how schema
+versioning works.
 
+### Initial schema
+
+Here's the initial example schema:
 ```xml
 <messageSchema package="FIXBinaryTest" byteOrder="littleEndian">
-    <types>
-        <type name="int8" primitiveType="int8"/>
-    </types>
+
+<types>
+    <type name="int8" primitiveType="int8"/>
+</types>
 
 <message name="FIX Binary Message1" id="1" blockLength="4">
     <field name="Field1" id="1" type="int8" semanticType="int"/>
@@ -137,7 +142,13 @@ Initial version of a message schema
 </messageSchema>
 ```
 
-Second version - a new message is added
+### Adding elements to the schema
+
+Below adds new elements to the schema. Upon any update we must increment the
+`version` attribute. When there is no `version` attribute, the version is zero.
+Hence, our new version is one. This version applies to all change. 
+
+This update chooses to document updates with the `sinceVersion` attribute.
 
 ```xml
 <messageSchema package="FIXBinaryTest" byteOrder="littleEndian"
@@ -161,7 +172,9 @@ Second version - a new message is added
 </messageSchema>
 ```
 
-Third version - a field is added
+### Adding a field to a message
+
+This update changes a message from the initial schema and adds a type.
 
 ```xml
 <messageSchema package="FIXBinaryTest" byteOrder="littleEndian"
@@ -187,3 +200,10 @@ Third version - a field is added
 </message>
 </messageSchema>
 ```
+
+Notice field addition effects only the version of the field: We don't update
+`sinceVersion` on a message when we add a field to it.
+
+*Note:* `sinceVersion` is not required, and has no default interpretation. In
+other words, "FIX Binary Message1" cannot be assumed as since version zero. To
+clarify this, consider adding `sinceVersion` on initial schema elements.

From 463af28484cb80b83e203309ef891d282192602a Mon Sep 17 00:00:00 2001
From: Adrian Cole <adriancole@users.noreply.github.com>
Date: Tue, 15 Dec 2020 07:31:12 +0800
Subject: [PATCH 2/2] less lies

---
 v2-0-RC3/doc/05SchemaExtensionMechanism.md | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/v2-0-RC3/doc/05SchemaExtensionMechanism.md b/v2-0-RC3/doc/05SchemaExtensionMechanism.md
index a7411ca..01c85e0 100644
--- a/v2-0-RC3/doc/05SchemaExtensionMechanism.md
+++ b/v2-0-RC3/doc/05SchemaExtensionMechanism.md
@@ -201,9 +201,5 @@ This update changes a message from the initial schema and adds a type.
 </messageSchema>
 ```
 
-Notice field addition effects only the version of the field: We don't update
-`sinceVersion` on a message when we add a field to it.
-
-*Note:* `sinceVersion` is not required, and has no default interpretation. In
-other words, "FIX Binary Message1" cannot be assumed as since version zero. To
-clarify this, consider adding `sinceVersion` on initial schema elements.
+Notice adding fields does not effect `sinceVersion` on the message that
+contains them.