fixup! fixup! Fixes #25917: Add a dedicated Readme for rudder-package

Fixes #25917: Add a dedicated Readme for rudder-package

relay/sources/rudder-pkg/Readme.md → relay/sources/rudder-pkg/README.md

@@ -2,9 +2,9 @@
 
 # Rpkg spec
 
-A rpkg is an `ar` archive containing with the `.rpkg` extension containing:
+A rpkg is an `ar` archive with the `.rpkg` extension containing:
 
-* a metadata in **Json**
+* a metadata in **JSON**
 * a tarball named `scripts.txz` containing the plugin package scripts if any
     * `preinst`
     * `postinst`
@@ -41,26 +41,26 @@ A rpkg is an `ar` archive containing with the `.rpkg` extension containing:
 | `name`             | String                | Yes           | The name of the plugin.                                    |
 | `version`          | String                | Yes           | The version of the compatible webapp and the version of the plugin concatenated by a `-`.                                 |
 | `description`      | String                | No            | A brief description of the plugin. This can be empty or omitted.                              |
-| `build-date`       | String (ISO 8601)     | Yes           | The date and time when the plugin was built, in ISO 8601 format.                              |
+| `build-date`       | String (RFC 3339)     | Yes           | The date and time when the plugin was built, in RFC 3339 format.                              |
 | `build-commit`     | String (SHA1 hash)    | Yes           | The Git commit hash associated with the build.                                                |
 | `jar-files`        | Array of Strings      | Yes           | A list of jar file names included in the plugin. An empty list if no jar files are needed.                                          |
-| `depends`          | Object                | No           | Lists dependencies required for the plugin to function. Each key represents a type of dependency (e.g., `binary`, `apt`, `rpm`, `python`) and maps to an array of specific dependencies. |
+| `depends`          | Object                | No           | Lists dependencies required for the plugin to function. Each key represents a type of dependency (`binary`, `apt`, `rpm` or `python`) and maps to an array of specific dependencies. |
 | `content`          | Object                | Yes           | Maps file archives to their installation paths within the system.                             |
 
 
 ### Subfields of `depends`
 | **Field** | **Type**          | **Mandatory** | **Details**                                                                  |
 |-----------|-------------------|---------------|------------------------------------------------------------------------------|
-| `binary`  | Array of Strings | No            | Dependencies that are binary packages.                                        |
-| `apt`     | Array of Strings | No            | Dependencies for Debian-based systems.                                        |
+| `binary`  | Array of Strings | No            | Dependencies that are binary packages and have to be available in `PATH`.     |
+| `apt`     | Array of Strings | No            | Dependencies for APT-based systems.                                        |
 | `rpm`     | Array of Strings | No            | Dependencies for RPM-based systems.                                           |
 | `python`  | Array of Strings | No            | Dependencies that are Python packages.                                        |
 
 ### Version format
 
 The `version` field listed in the metadata is built from the Rudder version the plugin was built for and the actual plugin version, concatenated by a `-`. It can be seen as `<Rudder webapp version>-<plugin version>`.
 
-A plugin is only compatible with a Rudder webapp in the exact same version than the one listed in the `version` field of its metadata. For instance, a plugin with a metadata containing 
+A plugin is only compatible with a Rudder webapp in the exact same version than the one listed in the `version` field of its metadata. For instance, a plugin with a metadata containing
 ```json
 "version": "8.0.1~rc3-2.9"
 ```
@@ -109,11 +109,37 @@ Each content archive must be listed in the metadata under the `contents` field,
 
 A failure in any of the steps in the schema below will abort the plugin installation without cleaning.
 
-[![](https://mermaid.ink/img/pako:eNp1U0tz2jAQ_isanSHExpTEh840QBKSaQ-0PrR2D8JaQMWWNJJMQoD_XlmSmdCHDiut9vl9Wh1wKSjgFK8q8VJuiDLo27TgyC7dLNeKyA1ayO0aMa4NqSpimODe_ilfAKHIbADVYAglhvz0lrt8soFyi15gSaREpailjVuyipl9cJkEFwoSOAVeMtDBND3MNWIGEY4aaTugcPKGWT57NYqUBqm2I0nKLVkD0qVi0nTR9_mi4UgqaBsOtmB6uIwvBTfAO-NjnkkLARyeABYoklWzZhy14JZEQ3Ce-yJCm7-rPOUzTpYVoF9EoRWrwIJZWTAd8mdLm81uifb0hGvLwh-0Zzy0gURFQaEdKH0mP4vyKdOuTtvwf2plsS1Wi513UmCfz2LyjhXTrWLBtbZ_48yG7-MpUFa6DMF75Ruzp8GOqIFqqFUH4V26B8mS9zm6SCVqn_OyoGMhjBfq9z-iOycnToa5nDrl-EUcZxcX30EfsyiMiru6d_LByUcn504-OflcnLl0ehb7bei3xG22BO7hGlRNGLXf5NCGFNi2XkOBU3ukRG0LXPCT9SONEV_3vMSpUQ30sBLNeoPTFam01Ro3YFNG7PvW51tJ-A8h6i7EcmyE-uw_pfubzgWnB_yK02QYXyXJTZzE0c141MN7nPavr67bNYqj29toPIqi0YdxMh6eevjN5Y1OvwGl5T4S?type=png)](https://mermaid.live/edit#pako:eNp1U0tz2jAQ_isanSHExpTEh840QBKSaQ-0PrR2D8JaQMWWNJJMQoD_XlmSmdCHDiut9vl9Wh1wKSjgFK8q8VJuiDLo27TgyC7dLNeKyA1ayO0aMa4NqSpimODe_ilfAKHIbADVYAglhvz0lrt8soFyi15gSaREpailjVuyipl9cJkEFwoSOAVeMtDBND3MNWIGEY4aaTugcPKGWT57NYqUBqm2I0nKLVkD0qVi0nTR9_mi4UgqaBsOtmB6uIwvBTfAO-NjnkkLARyeABYoklWzZhy14JZEQ3Ce-yJCm7-rPOUzTpYVoF9EoRWrwIJZWTAd8mdLm81uifb0hGvLwh-0Zzy0gURFQaEdKH0mP4vyKdOuTtvwf2plsS1Wi513UmCfz2LyjhXTrWLBtbZ_48yG7-MpUFa6DMF75Ruzp8GOqIFqqFUH4V26B8mS9zm6SCVqn_OyoGMhjBfq9z-iOycnToa5nDrl-EUcZxcX30EfsyiMiru6d_LByUcn504-OflcnLl0ehb7bei3xG22BO7hGlRNGLXf5NCGFNi2XkOBU3ukRG0LXPCT9SONEV_3vMSpUQ30sBLNeoPTFam01Ro3YFNG7PvW51tJ-A8h6i7EcmyE-uw_pfubzgWnB_yK02QYXyXJTZzE0c141MN7nPavr67bNYqj29toPIqi0YdxMh6eevjN5Y1OvwGl5T4S)
-
-
+```mermaid
+flowchart TD
+    subgraph Rpkg installation
+    A[Read the metadata]
+    B[Check webapp compatibility]
+    C[Check dependencies]
+    D{Is it an upgrade}
+    E[Extract rpkg package scripts]
+    F[Run preinst script]
+    G[Extract rpkg content]
+    H[Update the installed plugin database]
+    I[Run postinst script]
+    J[Enable jar files if any]
+    K[Restart webapp]
+    end
+    subgraph Uninstall older version
+    U1[Disable the jar files if any]
+    U2[Remove the related files listed in the plugin database]
+    U3[Remove the dedicated plugin folder in /var/rudder/packages]
+    U4[Remove the plugin from the database]
+    end
+
+    A --> B --> C --> D
+    D --> |No|E
+    D --> |Yes|U1
+    E --> F --> G --> H --> I --> J --> K
+
+    U1 --> U2 --> U3 --> U4 --> E
+```
 
-## Guidelines to write a Plugin
+## Guidelines to write a plugin
 
 * Do not deploy anything or create files under `/var/rudder/packages/rudder-plugin-<plugin-name>` as this folder is reserved for the package scripts and may be removed by the package manager.
 * A dedicated default folder `/var/rudder/plugins/rudder-plugin-<plugin-name>` is expected to contain most of the plugin unpacked files.