elenst and wlad have convincingly argued that we cannot really support downgrading, except in some special cases. At best, it is a ‘best effort’ that we are not testing. While I am fairly confident that a downgrade 10.3→10.2→10.1 should work as far as InnoDB is concerned, we do not test it, and thus we cannot really guarantee it. Furthermore, I cannot speak for other components of the server; for example, I have no idea how hard it would be to undo any changes made by any upgrade scripts.

Upgrades should considered a ‘point of no return’. That is, upgrades should be planned and prepared in such a way that downgrading should never be needed.

1. Extensively test the upgrade in a staging environment before going live. This could include deploying a ‘disposable’ upgraded read-only slave for an extensive period of time.
2. As soon as you start to use any new features supported by the upgraded server, a downgrade may become increasingly harder.

Note that even a downgrade by replaying a logical dump from the upgraded server may fail due to changes in the logical dump format, even if no new features were taken into use.

I'd like to add that it's not just "we don't test it" (and we don't, marko is right about it), and it cannot be solved by "starting to test". Yes, we can discover that "it might work in some special cases", but that's doesn't translate into a procedure.

We literally have nothing to test, we don't have downgrade tools or downgrade capabilities for major downgrade, like we have for upgrade. There is no way (to my knowledge) to restore the system tables to the previous format (and the claim that additional columns or longer data types in system tables shouldn't affect anything is worse than weak, because even if it's so, we can't know how system tables are used by third-party tools); there is no way to make mysqldump dump the structures in a given format suitable for an old version; there is no way to check that extra engines which possibly do not support downgrades are properly disabled (TokuDB comes to mind); there is no way to clean up configured authentication methods that previous versions do not support; and so on, and so forth, it can be continued for a long time.

There is nothing to document now except that "Currently there is no support for downgrades, apart from restoring a full backup made before upgrading, and starting the old version on it". Everything else would be not just an over-promise, but a "go" to users for an exercise which is likely to be damaging.

I think we need to consider downgrade as a properly planned (on all layers), evaluated and implemented feature for one of future major releases, and not to make empty promises until it's done.

I will create an article based on Elena and Marko's comments above.

One more comment: I do not think that it is feasible to implement any support for downgrade after an InnoDB crash. I can imagine that someone could get a crash (or hang or whatever) after an upgrade. If they just kill the server, they would be unable to downgrade. They should of course have created backups or tested the upgrade first in a staging environment. But if they failed all that, then the best bet could be to set innodb_force_recovery=3 and try to dump all data. For this kind of audience, it is better to emphasize that we do not support downgrade, but it might work in some special cases, if a number of precautions are taken.

greenman, regarding downgrades to 10.1 we should document this bit that should be part of all 10.1 release notes starting with 10.1.21:

A file format compatibility bug that was introduced in MariaDB 10.1.0 was fixed in MariaDB 10.1.21.

Using page_compression or non-default innodb_page_size created files that were incompatible with MariaDB 10.0 or MySQL 5.6. MariaDB 10.1.21 and higher will convert affected files from earlier MariaDB 10.1 releases to a compatible format.

This prevents a downgrade to earlier MariaDB 10.1 versions.

See the commit for details.

And because of this, we should also document that downgrading from 10.1.0‥10.1.20 to 10.0 when using non-default innodb_page_size cannot possibly work.

greenman, there is one more issue: unable to downgrade to MariaDB 10.2.6.
MDEV-12873 fixes a file format incompatibility bug that was present in MariaDB 10.2.2 to 10.2.6 (including the first GA version 10.2.6). This fix prevents the downgrade to MariaDB 10.2.6. I just added the following to the MariaDB 10.2.7 release notes. I do not think it is worth mentioning in later 10.2 release notes, because only the very first GA version 10.2.6 is affected by the inability to downgrade.

A file format compatibility bug that was introduced in MariaDB 10.2.2 was fixed in this version of MariaDB.

Creating tables with the attribute page_compressed=yes created InnoDB internal data dictionary records that are incompatible with MariaDB 10.1. MariaDB 10.2.7 and later will write the dictionary in a compatible way with MariaDB 10.1 and will also support the malformed metadata from affected 10.2 versions.

This may prevent a downgrade to earlier MariaDB 10.2 versions.

See the commit for details.

https://mariadb.com/kb/en/library/downgrading-between-major-versions-of-mariadb/