Merge pull request #4476 from esl/MIM-2384_migration_exml

MIM-2384 Prepare migration proposals after the exml changes from 4.0.0

Author: chrzaszcz

doc/migrations/6.3.1_6.x.y.md

@@ -36,3 +36,48 @@ It is also possible to completely disable client certificate verification during
 handshake in `just_tls` by setting `tls.verify_mode` to `none`.
 
 For more information regarding configuration of TLS for C2S see [Listener modules](../listeners/listen-c2s/#tls-options-for-c2s)
+
+## `exml` upgraded to 4.0
+
+### Change of internal format of XML messages affects the ways to upgrade MongooseIM cluster
+
+`exml` library used for parsing and emitting of XML messages was upgraded to version 4.0.
+In this new version internal representation of XML elements changed - element attributes
+are stored in a map (previously in a key value list).
+
+This is a disruptive change, and rollback to previous version is not possible.
+
+Parsed XML messages are being sent within MongooseIM cluster between Erlang nodes in internal representation,
+so to understand received messages (Erlang terms), all nodes must have the same code that handle XML elements. This makes a rolling upgrade
+(an upgrade of a cluster node by node) not viable for this release.
+
+One solution is to stop the whole MongooseIM cluster, upgrade and start again.
+
+The second solution is to configure a new cluster running new version
+alongside the old cluster, and migrate traffic from the old one to the new one.
+
+There is a third solution, which allows to maintain service availability but not requiring building a full new cluster.
+In this solution, you upgrade nodes one by one (like in the rolling upgrade), but change configuration to not allow
+upgraded node to rejoin the old cluster, but instead run as a new cluster.
+That way all nodes are migrated one by one to the newly formed cluster. Both clusters have access the same database.
+
+One warning regarding this solution: There is a corner case regarding access to archived messages only while both clusters
+are operating simultaneously. It may happen that users still connected to the old cluster try to retrieve newly archived messages.
+This will result in errors and possibly crashes as the old code doesn't recognise new internal representation.
+We just want to warn the operator about such possibility, the chance of it happening is slight, as we recommend the upgrade
+to be undertaken during the time of minimal traffic.
+
+### Archived XML - mod_mam
+
+Change of XML element representation also affects stored or archived messages, if they are stored in the internal Erlang term format.
+
+There is a config setting `modules.mod_mam.db_message_format` which controls the message format for archived messages
+and its default is different depending on the database backend used.
+The default for RDBMS databases is `mam_message_compressed_eterm` (which is Erlang term format) while for Cassandra it is `mam_message_xml`.
+
+Messages stored in XML textual format (`mam_message_xml`) are not affected by `exml` version change.
+
+For messages stored as Erlang term (`mam_message_compressed_eterm` or `mam_message_eterm`), we provide transparent retrieval of the old format, while new messages will be written in the archive in
+the new format. This means that the change of the format is transparent in operations of MongooseIM.
+However if you have external tools accessing message archive, you may need to verify that they work correctly with the new internal XML element representation.
+