Didn't address another thing, which I found confusing. In the "Message schema extension example", three versions are discussed, but only 2 version numbers are used. It could be more clear to use a different word if "a new message is added" is intentionally mutating an existing version. For example, instead of saying "Second version - a new message is added", you could say "First change - a new message is added to an existing version". This reduces the pressure on the word "version" used for different reasons in the same section. If on the other hand it was a typo to not increment the version, we should fix that :D
Didn't address another thing, which I found confusing. In the "Message schema extension example", three versions are discussed, but only 2 version numbers are used. It could be more clear to use a different word if "a new message is added" is intentionally mutating an existing version. For example, instead of saying "Second version - a new message is added", you could say "First change - a new message is added to an existing version". This reduces the pressure on the word "version" used for different reasons in the same section. If on the other hand it was a typo to not increment the version, we should fix that :D