From d2aff54a70f2ae8dd06d6fbc6cb5db8f7abe36f8 Mon Sep 17 00:00:00 2001 From: Tomas Kopecek Date: Tue, 19 Nov 2019 09:59:02 +0100 Subject: [PATCH] document tag inheritance Fixes: https://pagure.io/koji/issue/1757 --- docs/source/index.rst | 1 + docs/source/tag_inheritance.rst | 145 ++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 docs/source/tag_inheritance.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index 086842e9..bc096fbd 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/tag_inheritance.rst b/docs/source/tag_inheritance.rst new file mode 100644 index 00000000..660e5170 --- /dev/null +++ b/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.