From 40e66098d1d4fadad9bd1b3ef4610b291805bfe9 Mon Sep 17 00:00:00 2001
From: Nelson Kopliku <nelson.kopliku@suse.com>
Date: Thu, 9 Feb 2023 19:37:42 +0100
Subject: [PATCH] Update package_version gatherer doc

---
 guides/gatherers.md | 63 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 54 insertions(+), 9 deletions(-)

diff --git a/guides/gatherers.md b/guides/gatherers.md
index 90c3216d..7ef268a2 100644
--- a/guides/gatherers.md
+++ b/guides/gatherers.md
@@ -295,14 +295,23 @@ Example output (in Rhai):
 **Argument required**: yes.
 
 This gatherer supports two usecases:
- - get the version as a string of the specified package (useful to check if the installed version of a package is the same across multiple nodes)
- - compare a given version string against the installed version string of a given package.
+ - get information about the installed versions of the specified package
+ - compare a given version string against the latest installed version of a given package.
 
-While for the first usecase, a simple string containing the version is returned, for the second usecase, the return value is as follows (see additional details [here](https://fedoraproject.org/wiki/Archive:Tools/RPM/VersionComparison#The_rpmvercmp_algorithm)):
+In the first usecase a list of objects is returned, where each object carries relevant information about an installed version of a package.
+
+> Note:
+> - a list of one element is often expected since usually the installed version would be only one
+> - detected installed versions list is ordered by descending installation time: **latest installed versions come first**
+> - operating on the latest installed version requires accessing the first element in the list via `package_fact_name[0]` or `package_fact_name.first()`
+
+In the second usecase, the return value is as follows (see additional details [here](https://fedoraproject.org/wiki/Archive:Tools/RPM/VersionComparison#The_rpmvercmp_algorithm)):
  - A value of `0` if the provided version string matches the installed package version for the requested package.
  - A value of `-1` if the provided version string is older that what's currently installed.
  - A value of `1` if the provided version string is newer than what's currently installed.
 
+> The latest detected installed version is used for comparison
+
 Naming the facts / expectations accordingly is specially important here to avoid confusion.
  - We suggest using a `compare_` prefix for package version comparisons and `package_` to retrieve
    a package version
@@ -316,6 +325,14 @@ facts:
     gatherer: package_version
     argument: corosync,2.4.5
 
+  - name: package_corosync
+    gatherer: package_version
+    argument: corosync
+  
+  - name: package_sbd
+    gatherer: package_version
+    argument: sbd
+
 values:
   - name: greater_than_installed
     default: 1
@@ -327,14 +344,20 @@ values:
 expectations:
   - name: compare_package_corosync
     expect: facts.compare_package_corosync == values.greater_than_installed
+  
+  - name: compare_package_corosync
+    expect: facts.package_corosync.first().version == "2.4.5"
+
+  - name: sbd_version_same_on_all_hosts
+    expect_same: facts.package_sbd.firts().version
 ```
 
 Example arguments:
 
-| Name                 | Return value                                                 |
-| :------------------- | :----------------------------------------------------------- |
-| `package_name`       | a string containing the installed version of the rpm package |
-| `package_name,2.4.5` | an integer with a value of `-1`, `0` or `-1` (see above)     |
+| Name                 | Return value                                                                  |
+| :------------------- | :---------------------------------------------------------------------------- |
+| `package_name`       | a list containing information about the installed versions of the rpm package |
+| `package_name,2.4.5` | an integer with a value of `-1`, `0` or `-1` (see above)                      |
 
 Example specification:
 
@@ -347,6 +370,10 @@ facts:
   - name: package_pacemaker
     gatherer: package_version
     argument: pacemaker
+  
+  - name: multiple_sbd_versions_installed
+    gatherer: package_version
+    argument: sbd
 
   - name: compare_package_corosync
     gatherer: package_version
@@ -359,10 +386,28 @@ Example output (in Rhai):
 
 ```ts
 // package_corosync
-"2.4.5";
+[
+  #{
+    "version": "2.4.5"
+  }
+]
 
 // package_pacemaker
-"2.0.4+20200616.2deceaa3a";
+[
+  #{
+    "version": "2.0.4+20200616.2deceaa3a"
+  }
+]
+
+// multiple_sbd_versions_installed
+[
+  #{
+    "version": "1.5.1" // latest installed version, not necessarily the newest one
+  },
+  #{
+    "version": "1.5.2"
+  }
+]
 
 // compare_package_corosync
 0