Reiser4 development model
1. Why to track compatibility?
Reiser4 is in permanent development. New plugins managing new disk objects are added systematically. And the common problem is that old software is unaware of new objects. The biggest concern is old fsck utilities, which treat the new "unknown" objects as corruption. So we need a mechanism to restrict, or even prevent access to new objects for old software.
2. Reiser4 development policy
Here we discuss things needed to keep a track of compatibility, so we don't consider upgrades, which are fully backward and forward compatible (like adding discard/TRIM support).
Other upgrades of reiser4 kernel module (reiser4progs) always look like adding a plugin or a set of plugins of existing, or new interfaces. Hence, such upgrades are always backward compatible.
With every such upgrade developer has to increment plugin library version number of both, reiser4 kernel module and reiser4progs. See definition of the macro PLUGIN_LIBRARY_VERSION in reiser4 kernel module and reiser4progs.
3. Software Format Release Numbers
Any reiser4 kernel module (reiser4progs package) has a software format release number (SFRN) 4.X.Y, where X and Y are major and minor SFRN respectively.
Major SFRN of reiser4 module (reiser4progs) is defined as the maximal serial number of supported disk format plugin (see definition of the struct disk_format_plugin).
Minor SFRN of reiser4 module (reiser4progs) is defined as version number of the plugin library.
SFRN of reiser4 kernel module is reported by kernel (look for the string "Loading Reiser4 (format release: 4.X.Y)" in kernel messages.
SFRN of reiser4progs is reported by every utility provided by this package when specifying option -V (Look for the string "Format release 4.X.Y").
Don't confuse SFRN and the version number of reiser4progs package! The last one takes into account all software changes (including fully compatible ones).
4. Compatibility of software upgrades
Every upgrade of reiser4 kernel module and reiser4progs performed in accordance with the development model (section 1) is automatically backward compatible.
Every upgrade of reiser4progs SFRN is forward incompatible. That is, reiser4progs will refuse to with any partition with greater DFVN. This is for more reliability: fsck treats any "unknown" objects as a corruption.
"Major" upgrades of reiser4 kernel module (4.X.Y) -> (4.X+1.Y) are fully forward incompatible.
"Minor" upgrades of reiser4 kernel module (4.X.Y) -> (4.X.Y+1) are partially forward compatible.
5. Disk format version numbers
Any reiser4 partition has a disk format versions number (DFVN) 4.A.B, where A and B are respectively major and minor DFVN.
Major DFVN is defined as the serial number of disk format plugin specified when formatting the partition. Major DFVN never changes.
Minor DFVN is defined as the minimal version of the plugin library fully compatible with this partition. Initially every partition gets minor DFVN equal to minor SFRN of the mkfs.reiser4 utility when formatting the partition. Further minor DFVN can be upgraded.
Any partition 4.A.B can be correctly handled only by reiser4progs 4.U.V, where A <= U and B <= V. Otherwise, reiser4progs will refuse to work with such partition (user will be suggested to upgrade reiser4progs).
Any partition 4.A.B can be fully mounted only by kernel module 4.U.B, where A <= U.
If A > U, then mount will fail with a kernel warning about forward incompatibility and a suggestion to upgrade the kernel.
When mounting a partition 4.A.B by kernel module 4.U.V, where A <= U, B != V, then 2 scenarios are possible:
If B > V, then mount will succeed, but kernel will warn about partial forward compatibility (it means that not all disk objects will be accessible in that mount session).
If B < V, then mount will succeed. Kernel will upgrade DFVN in the primary superblock with the suggestion to upgrade DFVN in the superblock replicas (backup blocks) by running fsck.reiser4 --fix.
DFVN can be fully upgraded by any reiser4.fsck utility of proper SFRN. Reiser4 kernel module upgrades DFVN only in the primary superblock. Downgrades of DFVN are not supported/planned.
DFVN is reported by kernel at mount time (look for the string: "reiser4: found disk format 4.A.B"). DFVN is also reported by debugfs.reiser4 utility in default mode.