#1817 document tag inheritance
Merged 2 years ago by tkopecek. Opened 2 years ago by tkopecek.
tkopecek/koji issue1757  into  master

file modified
+1
@@ -26,6 +26,7 @@ 

      defining_hub_policies

      external_repo_server_bootstrap

      image_build

+     tag_inheritance

      misc

      release_notes/release_notes

      migrations/migrations

@@ -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 can it 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 about 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 not 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 this case, we only want

+    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.

Metadata Update from @tkopecek:
- Pull-request tagged with: no_qe

2 years ago

This is incredibly helpful. Thank you.

'don't need to care' should be 'don't need to care about'

'may don't want to' should be 'may not want to'

'we from some reason' should be 'we for some reason'. Or, 'In this case, we only want packages from...'

'how it can be configured' should be 'how can it be configured'

1 new commit added

  • grammar fixes
2 years ago

Commit 2f5c045 fixes this pull-request

Pull-Request has been merged by tkopecek

2 years ago