From 00f465e5e1c57d6b3e5a170bb6d8c132f8561635 Mon Sep 17 00:00:00 2001
From: Markus Pesch <markus.pesch@cryptic.systems>
Date: Wed, 9 Sep 2026 21:31:31 +0200
Subject: [PATCH] fix(meta): declare the versions the role actually requires

The role claimed to work with ansible 2.9, but two of its building blocks did not exist back then. The path_join
filter was introduced in ansible-base 2.10 and the btrfs_subvolume module in community.general 6.6.0, which in turn
requires ansible-core 2.11. Running the role on 2.9 therefore failed with an undefined filter instead of a readable
message about an unsupported control node.

The collection is now declared in a requirements.yml, mirroring the layout of the certificate_authority role, and the
lower bound is pinned because an older community.general still resolves but lacks the btrfs module. The linter
workflow installs that file, because ansible-lint cannot resolve the btrfs_subvolume tasks without the collection
being present, which only surfaced in CI where no collections are preinstalled.

Co-authored-by: Copilot <copilot@github.com>
---
 .gitea/workflows/ansible-linters.yaml |  1 +
 README.md                             | 11 +++++++++++
 meta/main.yaml                        |  2 +-
 requirements.yml                      |  6 ++++++
 4 files changed, 19 insertions(+), 1 deletion(-)
 create mode 100644 requirements.yml

diff --git a/.gitea/workflows/ansible-linters.yaml b/.gitea/workflows/ansible-linters.yaml
index 0b81b76..f88f2ef 100644
--- a/.gitea/workflows/ansible-linters.yaml
+++ b/.gitea/workflows/ansible-linters.yaml
@@ -17,4 +17,5 @@ jobs:
       uses: ansible/ansible-lint@665d9e07a1943254d2910faffc106adaf7ea7294 # v26.8.0
       with:
         args: "--config-file .ansible-lint"
+        requirements_file: "requirements.yml"
         setup_python: "true"
diff --git a/README.md b/README.md
index f75ac5e..dbc0f2f 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,17 @@ The ansible role `volker-raschek.unix-users` create and manage users on Linux ba
 Linux, Fedora and Ubuntu. Furthermore, the role can also be used to create groups, `~/.forward`, `~/.netrc` and to
 manage the `~/.ssh` directory.
 
+## Requirements
+
+The role requires `ansible-core` 2.11 or newer. A home directory can optionally be created as btrfs subvolume, which
+relies on the `btrfs_subvolume` module of the collection `community.general`.
+
+```bash
+ansible-galaxy collection install -r requirements.yml
+```
+
+The role manages users, groups and their home directories, so it has to be executed with `become: true`.
+
 ## Examples
 
 ### User and group
diff --git a/meta/main.yaml b/meta/main.yaml
index 6ae3420..92b4618 100644
--- a/meta/main.yaml
+++ b/meta/main.yaml
@@ -9,7 +9,7 @@ galaxy_info:
   - unix
   - linux
   license: "MIT"
-  min_ansible_version: "2.9"
+  min_ansible_version: "2.11"
   namespace: volker-raschek
   platforms:
   - name: ArchLinux
diff --git a/requirements.yml b/requirements.yml
new file mode 100644
index 0000000..c91ae82
--- /dev/null
+++ b/requirements.yml
@@ -0,0 +1,6 @@
+---
+
+collections:
+# The btrfs_subvolume module has been added in community.general 6.6.0.
+- name: community.general
+  version: ">=6.6.0"