Merge remote-tracking branch 'origin/issues/10'

* origin/issues/10:
  README: Point to example configuration
  Add an example file for projects configuration
  README: Change openmetrics section into configuration subsection
  README: Move "Use" section below "Requirements" section
  README: Update JSON payload section
  README: Fix typo in Configuration section
  README: Add section about promotion artifact
  Fix releng example configuration

README.rst

@@ -19,6 +19,11 @@ Requirements
 The arch-release-promotion tool is Python based. All requirements are specified
 in its `pyproject.toml <pyproject.toml>`_.
 
+Use
+===
+
+After installation, refer to the output of ``arch-release-promotion -h``.
+
 Configuration
 =============
 
@@ -27,7 +32,7 @@ The command-line tool ``arch-release-promotion`` makes use of two sources of con
 * `makepkg.conf <https://man.archlinux.org/man/makepkg.conf.5>`_ is read from
   any of its locations in the same priority as `makepkg
   <https://man.archlinux.org/man/makepkg.8>`_ does.
-  All of the below can also be based to the tool via environment variables:
+  All of the below can also be passed to the tool via environment variables:
 
   * ``GPGKEY`` is recognized for establishing which PGP key to use for signing
   * ``PACKAGER`` is recognized for establishing who is doing the signature and
@@ -44,23 +49,17 @@ The command-line tool ``arch-release-promotion`` makes use of two sources of con
     <https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>`_
     needs to provide write access for the target project.
 
-* `projects.toml` is a configuration file that provides the configuration for a
+* ``projects.toml`` is a configuration file that provides the configuration for a
   project and its releases. Configuration files are read and merged with
   descending priority from ``/etc/arch-release-promotion/projects.toml`` and
   ``$XDG_CONFIG_HOME/arch-release-promotion/projects.toml`` (which defaults to
   ``$HOME/.config/arch-release-promotion/projects.toml`` if
   ``$XDG_CONFIG_HOME`` is unset).
-  Please refer to the `example file <examples/projects.toml>`_ for further
+  Please refer to `examples/example.toml <examples/example.toml>`_ for further
   reference in regards to the available options
 
-Use
-===
-
-After installation, refer to the output of ``arch-release-promotion -h``.
-
-
 Openmetrics
-===========
+-----------
 
 If the upstream project offers an `openmetrics <https://openmetrics.io/>`_
 based metrics file, the data from it can be used as additional information in
@@ -69,7 +68,7 @@ the JSON payload.
 The following metrics are considered.
 
 Version metrics
----------------
+^^^^^^^^^^^^^^^
 
 Description and version information about e.g. packages can be derived from
 ``version_info`` metrics of type ``info``, that define a ``name``,
@@ -98,7 +97,7 @@ The above metrics entry would result in the following JSON representation:
    ]
 
 Size metrics
-------------
+^^^^^^^^^^^^
 
 Artifact size information in MebiBytes (MiB) and description can be derived
 from ``artifact_bytes`` metrics of type ``gauge``, that define a ``name`` and a
@@ -127,7 +126,7 @@ The above metrics entry would result in the following JSON representation:
    ]
 
 Amount metrics
---------------
+^^^^^^^^^^^^^^
 
 Information on the amount of something (e.g. packages) and description can be
 derived from ``data_count`` metrics of type ``summary``, that define a ``name``
@@ -155,8 +154,32 @@ The above metrics entry would result in the following JSON representation:
      }
    ]
 
+Promotion artifact
+==================
+
+The promotion artifact is a ZIP compressed file (``promotion.zip``), that is
+uploaded to the project before its link is added to the release that it is
+promoting.
+
+The file contains one directory for each release type that the project offers.
+In each release type directory there are is a **JSON payload**
+(``<release_type>-<version>.json``), a directory
+(``<release_type>-<version>/``) containing signatures for any files that have
+been setup for detached signatures and optionally a torrent file
+(``<release_type>-<version>.json``) that is created for the release type's
+build artifacts *and* the detached signatures contained in the promotion
+artifact.
+
+.. code::
+
+   example
+   ├── example-0.1.0
+   │   └── artifact.tar.gz.sig
+   ├── example-0.1.0.json
+   └── example-0.1.0.torrent
+
 JSON payload
-============
+------------
 
 The promotion of a release encompasses one or more JSON payloads, that describe
 each release type in the release.
@@ -164,51 +187,56 @@ each release type in the release.
 .. code:: json
 
    {
-     "developer": "Foobar McFooface <foobar@mcfooface.com>",
-     "files": ["something.txt", "something.txt.sig"],
-     "version_metrics": [
+     "amount_metrics": [
        {
-         "my-package": {
-           "description": "Version of my-package used for build",
-           "version": "1.0.0-1"
-         }
+         "name": "foo",
+         "description": "The amount of packages in foo",
+         "size": 369
        }
      ],
+     "developer": "Foobar McFooface <foobar@mcfooface.com>",
+     "files": ["something.txt", "something.txt.sig"],
+     "name": "foo",
+     "pgp_public_key": "SOMEONESPGPKEYID",
      "size_metrics": [
        {
-         "foo": {
-           "description": "Size of foo in MiB",
-           "size": 832
-         }
+         "name": "foo",
+         "description": "Size of foo in MiB",
+         "size": 832
        }
      ],
-     "amount_metrics": [
+     "torrent_file": "foo-0.1.0.torrent",
+     "version_metrics": [
        {
-         "foo": {
-           "description": "The amount of packages in foo",
-           "size": 369
-         }
+         "name": "my-package",
+         "description": "Version of my-package used for build",
+         "version": "1.0.0-1"
        }
      ],
-     "name": "foo",
-     "pgp_public_key": "SOMEONESPGPKEYID",
-     "torrent_file": "foo-0.1.0.torrent",
      "version": "0.1.0"
    }
 
+* ``amount_metrics``: A list of objects that describe the amount of something
+  (optional). The list depends on whether the project's configuration defines
+  ``amount_metrics`` and whether those metrics are available in the specific
+  release.
 * ``developer``: The full uid of the person promoting (and optionally signing
   artifacts in) the release type.
 * ``files``: A list of files in the release type.
-* ``info`` (optional): Additional info about the (creation of) the release
-  type. The value depends on whether configuration of the release type defines
-  at least one value in its list of ``info_metrics`` and whether this is found
-  in the release's metrics file.
 * ``name``: The name of the release type.
 * ``pgp_public_key``: The PGP key ID of the key signing files in the release
   type.
+* ``size_metrics``: A list of objects that describe the size of something
+  (optional). The list depends on whether the project's configuration defines
+  ``size_metrics`` and whether those metrics are available in the specific
+  release.
 * ``torrent_file`` (optional): The name of a torrent file created for the
   release type. The value depends on whether the configuration for the release
   type sets ``create_torrent`` to ``True``.
+* ``version_metrics``: A list of objects that describe the version of something
+  (optional). The list depends on whether the project's configuration defines
+  ``version_metrics`` and whether those metrics are available in the specific
+  release.
 * ``version``: The version of the release type.
 
 License

examples/example.toml

+# A list of tables that defines settings for each project.
+# Each project defines a [[projects]] list of tables and its individual
+# settings.
+[[projects]]
+# The group and name of the project.
+name = "group/example"
+# The name of the job that provides build artifacts for releases.
+job_name = "build"
+# The name of a metrics file that resides in the release's output directory
+# (optional).
+metrics_file = "metrics.txt"
+# The name of the directory in which the release's artifacts reside.
+output_dir = "output"
+# A list of release types and their configurations.
+releases = [
+  # Each release type is described as an object.
+  # NOTE: TOML does not allow a trailing comma in an object (the last attribute
+  # does not have a trailing comma).
+  {
+    # A list of names matching openmetrics labels, that track amounts of
+    # something, to be extracted from the metrics file (optional).
+    amount_metrics = ["example_amount"],
+    # Whether to create a torrent file for the release type.
+    create_torrent = true,
+    # A list of file extensions (only the last part of the extension is matched
+    # against!) for which to create detached signatures.
+    extensions_to_sign = [".txt"],
+    # The name of the release type.
+    name = "example_a",
+    # A list of names matching openmetrics labels, that track the size of
+    # something, to be extracted from the metrics file (optional).
+    size_metrics = ["example_size"],
+    # A list of names matching openmetrics labels, that track the version of
+    # something, to be extracted from the metrics file (optional).
+    version_metrics = ["example_version"]
+  },
+]

examples/projects.toml

@@ -5,34 +5,65 @@ metrics_file = "metrics.txt"
 output_dir = "output"
 releases = [
   {
-    name = "bootstrap",
-    info_metrics = ["archiso"],
-    extensions_to_sign = [".tar.gz"],
+    amount_metrics = [
+      "bootstrap",
+    ],
     create_torrent = true,
+    extensions_to_sign = [".gz"],
+    name = "bootstrap",
+    size_metrics = [
+      "bootstrap",
+    ],
+    version_metrics = [
+      "archiso",
+      "pacman",
+      "systemd",
+    ]
   },
   {
+    extensions_to_sign = [".efi", ".lkrn", ".pxe"],
     name = "ipxe",
     version_metrics = [
       "archiso",
       "ipxe",
-    ],
-    extensions_to_sign = [".efi", ".lkrn", ".pxe"]
+    ]
   },
   {
+    amount_metrics = [
+      "iso",
+    ],
+    create_torrent = true,
     name = "iso",
+    extensions_to_sign = [".iso"],
+    size_metrics = [
+      "eltorito_efi_image",
+      "initramfs",
+      "iso",
+    ],
     version_metrics = [
+      "archinstall",
       "archiso",
       "linux",
-    ],
-    extensions_to_sign = [".iso"],
-    create_torrent = true,
+      "pacman",
+      "systemd",
+    ]
   },
   {
+    amount_metrics = [
+      "netboot",
+    ],
+    extensions_to_sign = [],
     name = "netboot",
+    size_metrics = [
+      "netboot",
+      "initramfs",
+    ],
     version_metrics = [
+      "archinstall",
       "archiso",
       "linux",
-    ],
-    extensions_to_sign = []
+      "pacman",
+      "systemd",
+    ]
   },
 ]