document tag inheritance

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

docs/source/index.rst

@@ -26,6 +26,7 @@ Contents
     defining_hub_policies
     external_repo_server_bootstrap
     image_build
+    tag_inheritance
     misc
     release_notes/release_notes
     migrations/migrations

docs/source/tag_inheritance.rst

@@ -0,0 +1,145 @@
+How tag inheritance works
+-------------------------
+
+Almost everything in koji is dealing with tag and their inheritance.
+What is it good for and how it can be configured?
+
+Every tag handles its own configuration and as an administrator you
+can live with just this. But true power of tag structure is hidden in
+inheritance. You can compose tags, use parent products from which are
+data inherited to new versions or other layered products and more.
+
+Each tag has this set of data:
+
+tag data
+   1. architectures - here is the set of architectures which will be
+      used in the moment, when given tag is used as a buildroot (in
+      other words, when it is used in target definition)
+   2. comps groups - similar to architectures, this data are used as
+      installation groups, when tag is used as a buildroot. Generally,
+      ``srpm-build`` and ``build`` groups are required in almost all
+      cases. There could be also some additional groups like
+      ``maven-build`` or ``livemedia-build`` for other operations,
+      than just building rpms. Groups can be created and edited via
+      ``*-group-*`` koji commands.
+   3. maven options - If maven builds are enabled in koji environment
+      (needs setup on hub's side), ``maven_support`` and
+      ``include_all`` are options related to it. First says, that
+      maven repositories should be generated and second one limits if
+      all tagged versions of some artifact should be present in such
+      repository.
+package list
+   Every tag carries a list of allowed packages, which can be tagged
+   there and also owner of such package/tag combination. Note, that
+   owner doesn't mean much in respect to who can do what. It is just a
+   default recipients of notifications and can be changed in any time.
+   Ownership doesn't limit anybody in un/tagging builds for that
+   tag/package. This is on the other hand driven by hub policies.
+   Package list simply says, what is allowed in tag (even if there is
+   no build for given package).
+tagged builds list
+   This is the last component of tag. Obviously it is a list of builds
+   for packages from previous point. It will never happen, that you'll
+   see some builds for which is not package listed above.
+
+All these three groups of data can be inherited and propagated through
+inheritance chains.
+
+Inheritance options
+___________________
+
+Whole inheritance can be edited via CLI's commands
+``add-tag-inheritance`` and ``edit-tag-inheritance``. They have same
+options which are described with examples here:
+
+Simple ``add-tag-inheritance`` requires two existing tags which will
+be linked together in inheritance chain.
+
+::
+
+   $ koji add-tag parent
+   $ koji add-tag child
+   $ koji add-tag-inheritance child parent
+   $ koji list-tag-inheritance child
+          child (168)
+     ....  └─parent (167)
+
+In the example you can see basic inheritance chain. You see ``child``
+tag which is inheriting data from ``parent`` tag. Numbers behind tag
+names are numeric ids, which you don't need to care in normal
+situations, but which can be useful in scripting koji. Four dots in
+the beginning of line are placeholders for different inheritance
+flags. These can be: M, F, I, N which denotes ``maxdepth``,
+``pkg_filter``, ``intransitive`` and ``noconfig`` respectively.  All
+these options can specified via CLI.
+
+``priority``
+    When you're adding new inheritance line to tag, which already has
+    some parent, you would like to denote, in which part of
+    inheritance chain new parent should appear. Let's continue with
+    previous example.
+
+    ::
+
+     $ koji add-tag less-significant-parent
+     $ koji add-tag-inheritance child less-significant-parent --priority 100
+     $ koji list-tag-inheritance child
+          child (168)
+     ....  ├─parent (167)
+     ....  └─less-significant-parent (169)
+
+    What happened here is, that ``parent`` has default priority 0,
+    while new one is priority 100. Lower number wins here. If you
+    change your mind, you can always use ``edit-tag-inheritance`` to
+    change the priority.
+
+    .. note::
+      Good rule of thumb is to not create inheritance without priority
+      and use 10's or 100's steps. In such case you shouldn't need to
+      update priorities, when adding something in the middle (where you
+      can use e.g. priority 15 like in good old Basic times).
+
+``maxdepth``
+   For longer inheritance chains you may don't want to treat whole
+   chain. Let's leave our example and get more real-life situation.
+
+   ::
+
+    $ koji list-tag-inheritance linux3-build
+         linux3-build (4380)
+    ....  └─linux3-override (4379)
+    ....     └─linux3-updates (4373)
+    ....        └─linux2 (4368)
+    ....           └─linux1 (4350)
+    ....              └─linux0 (4250)
+
+    $ koji add-tag linux4-build
+    $ koji add-tag-inheritance linux4-build linux3-build --maxdepth 0
+    $ koji list-tag-inheritance linux4-build
+         linux4-build (4444)
+    M...  └─linux3-build (4380)
+
+   This is not, what you would see in Fedora's koji, because Fedora is
+   not reusing anything from previous releases and is doing mass
+   rebuilds instead, but it could have. In such case, we from some
+   reason want only packages from ``linux3-build``, but not anything
+   inherited into it. ``maxdepth`` does exactly this and strips the
+   rest of inheritance chain.
+
+``intransitive``
+    Intransitive inheritance links are as what they say. If they are
+    used somewhere deeper in inheritance chain, they will be ignored.
+    It can be used for ensuring, that something will not be propagated
+    by mistake. In combination with ``maxdepth`` it can mean hard stop
+    even before ``maxdepth`` is reached.
+
+``noconfig``
+    While `normal` inheritance inherits everything - it means tag
+    configuration, package list and tagged builds, links with this
+    option are used only for propagating list of packages and builds.
+    Everything else is ignored (architectures, locks, permissions,
+    maven support).
+
+``pkg-filter``
+    Package filter is defined as regular expression and limits which
+    packages are propagated through this link.