diff --git a/man/os-release.xml b/man/os-release.xml
index 6be96cf8bc..15608c437a 100644
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -93,30 +93,36 @@
main system. Additionally, the presence of that file means that the system is in the initrd phase.
/etc/os-release should be symlinked to /etc/initrd-release
(or vice versa), so programs that only look for /etc/os-release (as described
- above) work correctly. The rest of this document that talks about os-release
- should be understood to apply to initrd-release too.
+ above) work correctly.
+
+ The rest of this document that talks about os-release should be understood
+ to apply to initrd-release too.
/usr/lib/extension-release.d/extension-release.IMAGE
/usr/lib/extension-release.d/extension-release.IMAGE
- for extension images plays the same role as os-release in the main system, and follows the
- same syntax and rules as described in the Portable Services Documentation.
- The purpose of this file is to allow the operating system to correctly match an extension image
- to a base OS image, This is typically implemented by first checking that the ID=
- options match, and if they do either SYSEXT_LEVEL= has to match too (preferred), or
- as a fallback if that is not present VERSION_ID= is checked. This ensures that ABI/API
- between the layers matches and no incompatible images are merged in an overlay.
- It is preferred that the extension-release.IMAGE filename is suffixed
- with the exact file name of the image that contains it, so that all such files in every layer of an overlay are visible.
- But for the purpose of parsing metadata, in case it is not possible to guarantee that an image file name is stable
- and doesn't change between the build and the deployment phases, the first and only file which name starts with
- extension-release., is located in the same directory and is tagged with a
- user.extension-release.strict xattr7
- set to the string 0, will be parsed instead, if the one with the expected name cannot be found.
- The rest of this document that talks about os-release should be understood to apply to
- extension-release too.
+ plays the same role for extension images as os-release for the main system, and
+ follows the syntax and rules as described in the Portable Services Documentation. The purpose of this
+ file is to identify the extension and to allow the operating system to verify that the extension image
+ matches the base OS. This is typically implemented by checking that the ID= options
+ match, and either SYSEXT_LEVEL= exists and matches too, or if it is not present,
+ VERSION_ID= exists and matches. This ensures ABI/API compatibility between the
+ layers and prevents merging of an incompatible image in an overlay.
+
+ In the extension-release.IMAGE filename, the
+ IMAGE part must exactly match the file name of the containing image with the
+ suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't
+ change between the build and the deployment phases, it is possible to relax this check: if exactly one
+ file whose name matches extension-release.* is present in this
+ directory, and the file is tagged with a user.extension-release.strict
+ xattr7 set to the
+ string 0, it will be used instead.
+
+ The rest of this document that talks about os-release should be understood
+ to apply to extension-release too.