compat: Improve the ABI documentation

Explain more clearly why sticking to a specific Landlock ABI version to
infer access rights is highly recommended.

Add links to the landlock-test-tools repository and related CI changes.

Signed-off-by: Mickaël Salaün <mic@digikod.net>

src/compat.rs

@@ -9,7 +9,8 @@ use strum_macros::{EnumCount as EnumCountMacro, EnumIter};
 
 /// Version of the Landlock [ABI](https://en.wikipedia.org/wiki/Application_binary_interface).
 ///
-/// `ABI` enables to get the features supported by a specific Landlock ABI.
+/// `ABI` enables to get the features supported by a specific Landlock ABI
+/// (without relying on the kernel version which may not be accessible or patched).
 /// For example, [`AccessFs::from_all(ABI::V1)`](Access::from_all)
 /// gets all the file system access rights defined by the first version.
 ///
@@ -18,12 +19,25 @@ use strum_macros::{EnumCount as EnumCountMacro, EnumIter};
 /// a moving target that would change the semantics of your Landlock rule
 /// when migrating to a newer version of this crate
 /// (i.e. non-breaking change with new supported features).
-/// This usage should then be considered indeterministic because requested features
+/// This usage is then an undefined behavior because requested features
 /// (e.g., access rights)
 /// could not be tied to the application source code.
 ///
-/// Such `ABI` is also convenient to get the features supported by a specific Linux kernel
-/// without relying on the kernel version (which may not be accessible or patched).
+/// Because we cannot know what would be the effect of an unknown (potential future) restriction,
+/// handling an untested Landlock access right (i.e. denied-by-default access)
+/// is then an undefined behavior for your application (i.e. it may work or not).
+/// This crate provides a set of tools to sandbox as much as possible
+/// while guaranteeing a consistent behavior thanks to the [`Compatible`] methods.
+/// You should also test with different relevant kernel versions,
+/// see [landlock-test-tools](https://github.com/landlock-lsm/landlock-test-tools) and
+/// [CI integration](https://github.com/landlock-lsm/rust-landlock/pull/41).
+///
+/// This way, we can have the guarantee that the use of a set of tested Landlock ABI works as
+/// expected because features brought by newer Landlock ABI will never be enabled by default
+/// (cf. [Linux kernel compatibility contract](https://docs.kernel.org/userspace-api/landlock.html#compatibility)).
+///
+/// In a nutshell, test the access rights you request on a kernel that support them and
+/// on a kernel that doesn't support them.
 #[cfg_attr(
     test,
     derive(Debug, PartialEq, Eq, PartialOrd, EnumIter, EnumCountMacro)

src/fs.rs

@@ -43,11 +43,11 @@ use strum::IntoEnumIterator;
 ///
 /// # Warning
 ///
-/// To avoid compile time behavior at run time,
-/// which may look like undefined behavior,
-/// don't use `BitFlags::<AccessFs>::all()` nor `BitFlags::ALL`,
-/// but [`AccessFs::from_all(ABI::V1)`](Access::from_all) instead.
-/// See [`ABI`] for the rational.
+/// To avoid undefined behaviors **don't use `BitFlags::<AccessFs>::all()` nor `BitFlags::ALL`**,
+/// but use a version you tested and vetted instead,
+/// for instance [`AccessFs::from_all(ABI::V1)`](Access::from_all).
+/// Direct use of **the [`BitFlags`] API is deprecated**.
+/// See [`ABI`] for the rationale and help to test it.
 #[bitflags]
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]