From ec73a2a2d17f91adf8a3745077515e97b6a7e111 Mon Sep 17 00:00:00 2001
From: Tomas Kopecek <tkopecek@redhat.com>
Date: Jun 30 2020 13:27:31 +0000
Subject: [PATCH 1/3] doc: dist-repo and exporting repos


Fixes: https://pagure.io/koji/issue/1964

---

diff --git a/docs/source/exporting_repositories.rst b/docs/source/exporting_repositories.rst
new file mode 100644
index 0000000..6d38f52
--- /dev/null
+++ b/docs/source/exporting_repositories.rst
@@ -0,0 +1,26 @@
+======================
+Exporting repositories
+======================
+
+There are multiple ways how to export repositories from koji. In first place,
+koji is not a repository manager - it is a build system. anyway, due to
+architecture and build logic it know about some repositories, typically those
+needed to populate buildroots. These are stored at
+``<topdir>/repos/<tag_name>/<repo_id>`` and can be consumed by builders via
+http. Of course, other users can download them also. Anyway, these repos are by
+design not suited for distribution.
+
+Simplest way ho to create distribution-ready repo is to use ``koji dist-repo``
+command. It allows user with ``dist-repo`` permission (non-default requirements
+can be specified via :doc:`hub policy <defining_hub_policies>`. ``dist-repo``
+command takes two basic arguments, where first is the name of the tag, while
+second is signing key id. You can create also repositories from unsigned rpms by
+supplying non-sensual signing key and adding ``--allow-missing-signatures``.
+Further options can tell koji if debuginfo or source rpms are needed, if zck
+dictionaries or multilib support should be used, etc. Feel free to go through
+whole ``koji dist-repo --help``.
+
+If you're aiming to have more control about repositories, varieties of
+distribution flavours, etc. use `pungi <https://pagure.io/pungi/>`_ which can
+create whole composes and which uses koji for some of the subtasks. Pungi + koji
+is what Fedora currently uses for composes.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a7b3acb..3262ac8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -27,6 +27,7 @@ Contents
     external_repo_server_bootstrap
     image_build
     winbuild
+    exporting_repositories
     tag_inheritance
     misc
     release_notes/release_notes

From 24e9b77490a3b46a153fab13f19b28bedd84cc56 Mon Sep 17 00:00:00 2001
From: Mike McLean <mikem@redhat.com>
Date: Jul 21 2020 15:53:24 +0000
Subject: [PATCH 2/3] fix typos and minor grammar problems


---

diff --git a/docs/source/exporting_repositories.rst b/docs/source/exporting_repositories.rst
index 6d38f52..92cd344 100644
--- a/docs/source/exporting_repositories.rst
+++ b/docs/source/exporting_repositories.rst
@@ -2,20 +2,20 @@
 Exporting repositories
 ======================
 
-There are multiple ways how to export repositories from koji. In first place,
-koji is not a repository manager - it is a build system. anyway, due to
-architecture and build logic it know about some repositories, typically those
+There are multiple ways to export repositories from koji. In first place,
+koji is not a repository manager - it is a build system. Anyway, due to
+architecture and build logic it knows about some repositories, typically those
 needed to populate buildroots. These are stored at
 ``<topdir>/repos/<tag_name>/<repo_id>`` and can be consumed by builders via
 http. Of course, other users can download them also. Anyway, these repos are by
 design not suited for distribution.
 
-Simplest way ho to create distribution-ready repo is to use ``koji dist-repo``
-command. It allows user with ``dist-repo`` permission (non-default requirements
-can be specified via :doc:`hub policy <defining_hub_policies>`. ``dist-repo``
+The simplest way to create a distribution-ready repo is to use the ``koji dist-repo``
+command. It allows a user with ``dist-repo`` permission (non-default requirements
+can be specified via :doc:`hub policy <defining_hub_policies>`. The ``dist-repo``
 command takes two basic arguments, where first is the name of the tag, while
 second is signing key id. You can create also repositories from unsigned rpms by
-supplying non-sensual signing key and adding ``--allow-missing-signatures``.
+supplying a nonsense signing key and adding ``--allow-missing-signatures``.
 Further options can tell koji if debuginfo or source rpms are needed, if zck
 dictionaries or multilib support should be used, etc. Feel free to go through
 whole ``koji dist-repo --help``.

From 172659ad5af6739d822d24b51e1f84caac9a4de7 Mon Sep 17 00:00:00 2001
From: Mike McLean <mikem@redhat.com>
Date: Jul 21 2020 19:15:40 +0000
Subject: [PATCH 3/3] rewrite


---

diff --git a/docs/source/exporting_repositories.rst b/docs/source/exporting_repositories.rst
index 92cd344..58db802 100644
--- a/docs/source/exporting_repositories.rst
+++ b/docs/source/exporting_repositories.rst
@@ -2,25 +2,92 @@
 Exporting repositories
 ======================
 
-There are multiple ways to export repositories from koji. In first place,
-koji is not a repository manager - it is a build system. Anyway, due to
-architecture and build logic it knows about some repositories, typically those
-needed to populate buildroots. These are stored at
-``<topdir>/repos/<tag_name>/<repo_id>`` and can be consumed by builders via
-http. Of course, other users can download them also. Anyway, these repos are by
-design not suited for distribution.
+Koji provides some *limited* features for exporting repositories of RPMs.
+Please note that Koji is a build system, not a repository manager, and these
+features are secondary.
+If you need more robust repository generation than Koji provides, then you may
+want to look into using `pungi <https://pagure.io/pungi/>`_.
+
+
+Koji's internal repositories
+============================
+
+Koji uses yum repositories as part of its build process for RPMs.
+These repositories are used by the builders to generate buildroots.
+Their generation is focused on that purpose, and they are not really suitable
+for export.
+However, they can be useful for simple cases.
+
+Koji's internal repositories can be accessed at
+``<topdir>/repos/<tag_name>/<repo_id>``
+For a given tag name, there will be multiple repo ids over time as tag content
+changes.
+The current repo for a given tag can be determined with a call to ``getRepo``.
+
+For convenience, Koji also maintains a "latest" symlink for each tag:
+``<topdir>/repos/<tag_name>/latest``.
+Please note that this symlink changes over time, which could break a yum transaction.
+
+
+Dist-repos
+==========
 
 The simplest way to create a distribution-ready repo is to use the ``koji dist-repo``
-command. It allows a user with ``dist-repo`` permission (non-default requirements
-can be specified via :doc:`hub policy <defining_hub_policies>`. The ``dist-repo``
-command takes two basic arguments, where first is the name of the tag, while
-second is signing key id. You can create also repositories from unsigned rpms by
-supplying a nonsense signing key and adding ``--allow-missing-signatures``.
-Further options can tell koji if debuginfo or source rpms are needed, if zck
-dictionaries or multilib support should be used, etc. Feel free to go through
-whole ``koji dist-repo --help``.
+command.
+It allows users with access to generate a more robust yum repository from the
+contents of a given tag.
+These repos differ from the internal ones in several key ways:
+
+* generation is user-controlled via the ``dist-repo`` command
+* supports using signed rpms
+* supports multilib
+* allows for more customized comps data
+* supports deltarpm generation
+* can split debuginfo into separate repos
+* can generate zchunk files
+
+**Access control**
+
+In order to use the ``dist-repo`` command, a user must satisfy one of the
+following:
+
+* have the ``dist-repo`` permission
+* have the ``admin`` permission
+* satisfy the requirements of the ``dist_repo`` policy
+
+For more information about hub policies, see :doc:`defining_hub_policies`.
+
+
+**Usage**
+
+The ``dist-repo`` command takes a tag name and one or more key ids for signing keys.
+
+..
+
+    koji dist-repo [options] <tag> <key_id> [<key_id> ...]
+
+The ``tag`` argument must be a valid tag name.
+The resulting repository will be based on the contents of that tag.
+Any valid tag will work, whether or not it has an associated target.
+
+Koji will attempt to find a signed copy for each rpm matching one
+of the given ``key_id`` arguments (searching in the order given).
+Normally, Koji will error if there is no matching signed copy for any of the
+rpms.
+This behavior can be modified with the ``--allow-missing-signatures`` or
+``--skip-missing-signatures`` options.
+The ``key_id`` argument may be omitted entirely if the
+``--allow-missing-signatures`` option is specified.
+
+Various features of repo generation (e.g. multilib support, delta rpms, or
+zchunk files) are controlled via command options.
+For a full list of options, see ``koji dist-repo --help``.
+
+
+Beyond Koji
+===========
 
 If you're aiming to have more control about repositories, varieties of
 distribution flavours, etc. use `pungi <https://pagure.io/pungi/>`_ which can
-create whole composes and which uses koji for some of the subtasks. Pungi + koji
-is what Fedora currently uses for composes.
+create whole composes and which uses Koji for some of the subtasks.
+Pungi + koji is what Fedora currently uses for composes.

