Verified Commit 35cd8bd0 authored by David Runge's avatar David Runge
Browse files

README: Extend with information on arch-release-sync

README.rst:
Extend with information on arch-release-sync, how to configure it and
how its synchronization behaves.
Add gnupg explicitly to non-language dependencies for the tooling.
parent be85f200
......@@ -2,8 +2,8 @@
arch-release-promotion
======================
This project allows for promoting existing releases of a project in Arch
Linux's Gitlab instance.
This project allows for promotion and synchronization of existing releases of a
project in Arch Linux's Gitlab instance.
Releases of a project (e.g. ``project``) may consist of several release types
(e.g. ``image_a`` and ``image_b``), which are addressed separately.
......@@ -13,21 +13,30 @@ artifacts (optional), a torrent file (optional) and a JSON payload which can be
used by `archweb <https://github.com/archlinux/archweb>`_ to display
information about each release type.
Synchronization with a local directory can be achieved for a configurable
maximum amount of release versions (each consisting of their respective
configured release types) of a project.
Requirements
============
The arch-release-promotion tool is Python based. All requirements are specified
in its `pyproject.toml <pyproject.toml>`_.
Arch-release-promotion is Python based. All language specific requirements are
specified in its `pyproject.toml <pyproject.toml>`_.
Additionally, ``arch-release-promotion`` requires `gnupg <https://gnupg.org/>`_
to handle detached PGP signatures.
Use
===
After installation, refer to the output of ``arch-release-promotion -h``.
After installation, refer to the output of ``arch-release-promotion -h`` and
``arch-release-sync -h``.
Configuration
=============
The command-line tool ``arch-release-promotion`` makes use of two sources of configuration:
The command-line tools ``arch-release-promotion`` and ``arch-release-sync``
make use of two sources of configuration:
* `makepkg.conf <https://man.archlinux.org/man/makepkg.conf.5>`_ is read from
any of its locations in the same priority as `makepkg
......@@ -38,11 +47,11 @@ The command-line tool ``arch-release-promotion`` makes use of two sources of con
* ``PACKAGER`` is recognized for establishing who is doing the signature and
is important for `WKD
<https://wiki.archlinux.org/title/GnuPG#Web_Key_Directory>`_ lookup
* ``MIRRORLIST_URL`` (not used by makepkg) is used during the generation of torrent files to add
webseeds (defaults to
* ``MIRRORLIST_URL`` (not used by makepkg) is used during the generation of
torrent files to add webseeds (defaults to
``"https://archlinux.org/mirrorlist/?country=all&protocol=http&protocol=https"``)
* ``GITLAB_URL`` (not used by makepkg) is used to connect to a GitLab instance to select, download
and promote releases of a project (defaults to
* ``GITLAB_URL`` (not used by makepkg) is used to connect to a GitLab
instance to select, download and promote releases of a project (defaults to
``"https://gitlab.archlinux.org"``)
* ``PRIVATE_TOKEN`` (not used by makepkg) is used to authenticate against the
GitLab instance. The `personal access token
......@@ -239,7 +248,54 @@ each release type in the release.
release.
* ``version``: The version of the release type.
Synchronization
===============
The synchronization of releases works by retrieving the list of promoted
releases of the project from the remote. For each promoted release version, the
promotion artifact is downloaded and used to establish whether all of the
configured release types are fully synchronized.
Location and cleanup
--------------------
All release types for each release version are synchronized to a local
directory. The directory and and the maximum amount of synchronized release
versions are configurable globally or per project.
.. code::
sync_dir
├── example_a
│   ├── example_a-0.1.0
│   │   ├── foo.txt
│   │   └── foo.txt.sig
│   ├── example_a-0.1.0.json
│   ├── example_a-0.1.0.torrent
│   └── latest -> example_a-0.1.0
└── example_b
├── example_b-0.1.0
│   ├── bar.txt
│   └── bar.txt.sig
├── example_b-0.1.0.json
├── example_b-0.1.0.torrent
└── latest -> example_b-0.1.0
A ``latest`` symlink is created to point at the currently latest version of
each release type.
Any files and directories that are not owned by versions of release types of
the currently synchronized release versions are removed from the
synchronization directory.
If changes are introduced to files in the target directory (due to a
synchronization action), it is possible to write a Unix timestamp to a file
that is configurable globally or per project (the directory in which the file
resides in has to exist).
License
=======
Arch-release-promotion is licensed under the terms of the **GPL-3.0-or-later** (see `LICENSE <LICENSE>`_).
Arch-release-promotion is licensed under the terms of the **GPL-3.0-or-later**
(see `LICENSE <LICENSE>`_).
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment