diff --git a/docs/source/index.rst b/docs/source/index.rst index b7233f52..b052644e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -33,6 +33,7 @@ Contents repo_generation exporting_repositories tag_inheritance + managing_comps_data misc release_notes/release_notes migrations/migrations diff --git a/docs/source/managing_comps_data.rst b/docs/source/managing_comps_data.rst new file mode 100644 index 00000000..6cd4af45 --- /dev/null +++ b/docs/source/managing_comps_data.rst @@ -0,0 +1,157 @@ +Managing comps data for tags +============================ + +Koji can record comps data for each tag and uses that data to write a comps +file whenever it generates a yum repo for that tag. This document describes +how this data is stored, how to read it, and how to change it. + +For background on comps files, see + +* https://dnf5.readthedocs.io/en/latest/misc/comps.7.html +* https://fedoraproject.org/wiki/How_to_use_and_edit_comps.xml_for_package_groups + +The comps data *affects how rpm builds are performed*. +Various buildroots generated by Koji use these groups for their base install. +E.g. + +* rpm builds use the ``build`` group +* source rpm builds use the ``srpm-build`` group +* maven builds use the ``maven-build`` group +* wrapper rpm builds use the ``wrapper-rpm-build`` group +* appliance builds use the ``appliance-build`` group +* livecd builds use the ``livecd-build`` group +* livemedia builds use the ``livemedia-build`` group + + +Reading the data +---------------- + +The ``koji list-groups`` cli command will output the comps data for a given tag + +.. code-block:: text + + Usage: koji list-groups [options] [] + (Specify the --help global option for a list of other help options) + + Options: + -h, --help show this help message and exit + --event=EVENT# query at event + --ts=TIMESTAMP query at last event before timestamp + --repo=REPO# query at event for a repo + --show-blocked Show blocked packages and groups + +The command will optionally accept a group name to limit the output to a single group. + +Like many other types of data in Koji, the comps data is versioned and Koji remembers its history. +The ``--event/--ts/--repo`` options can be used to query this data from an earlier point in time. + +The ``show-blocked`` option will include blocked entries in the output. + +Alternately ``show-groups`` command can be used to present the groups data in different formats. +This command is a historical oddity, but still useful to export the data in comps format. + +Example +------- + +The following command prints the srpm-build group data for the f41-build tag. + +.. code-block:: text + + $ koji list-groups f41-build srpm-build + srpm-build [f41] + bash: None, mandatory [f41] + fedora-release: None, mandatory [f41] + fedpkg-minimal: None, mandatory [f41] + glibc-minimal-langpack: None, mandatory [f41] + gnupg2: None, mandatory [f41] + redhat-rpm-config: None, mandatory [f41] + rpm-build: None, mandatory [f41] + shadow-utils: None, mandatory [f41] + +Because our command included a specific group name, the command only outputs that one group. +Under this group, we see the list of packages in the group and their parameters. +The bracketed value at the end shows the tag that the entry is inherited from. + + +Groups data and inheritance +--------------------------- + +Like most other data associated with tags, groups data is inheritable. +Because the groups data is complex, so is the inheritance. +The groups data is inherited piecemeal, with individual groups, group package +entries, and group dependencies separately inheritable. + +You can prevent an entry from being inherited by blocking it. +This can be done via the ``block-group``, ``block-group-pkg``, and ``block-group-req`` +commands respectively (and undone with the corresponding unblock command). + +As noted above, you can see which tags an entry comes from via the ``list-groups`` command. + +So, a given tag will have a list of groups that includes inherited entries. +Each of those groups will have a list of packages and a list of group dependencies +which include inherited entries. + +For admin sanity, we recommend defining a comps in a base tag in your inheritance +and keeping adjustments in child tags to a minimum. +A common case is to add additional packages to the build group for a specialized +build tag. + + +Changing comps data +------------------- + +You can add, remove, block, and unblock individual entries with the relevant command + +.. code-block:: text + + add-group Add a group to a tag + remove-group Remove group from tag + block-group Block group in tag + unblock-group Unblock a group from tag + add-group-pkg Add a package to a group's package listing + remove-group-pkg Remove packages from a group's package listing + block-group-pkg Block a package from a group's package listing + unblock-group-pkg Unblock a package from a group's package listing + add-group-req Add a group to a group's required list + block-group-req Block a group's requirement listing + remove-group-req Remove entries from a group's requirement listing + unblock-group-req Unblock a group's requirement listing + +Additionally, you can also import groups data directly from a comps file with the ``import-comps`` command. +This is useful when setting up a new tag from scratch. + +.. code-block:: text + + Usage: koji import-comps [options] + (Specify the --help global option for a list of other help options) + + Options: + -h, --help show this help message and exit + --force force import + + +Blocking vs removing +-------------------- + +The various remove commands remove a specific entry from a specific tag. +They will fail if the entry is not actually in the specified tag. +This commonly happens when an entry is inherited. + +When your tag has an inherited comps entry that you want to remove, you have two +options: + +* block the entry in the tag +* remove the entry from the ancestor tag it is inherited from + +It is generally safest to block, as this only affects the tag of concern. +Removing the entry in an ancestor could affect other tags negatively. +However, there are certainly cases where it makes sense to remove the entry +from the ancestor. + + +Group dependencies +------------------ + +For historical reasons, Koji's comps data allows specifying group dependecies/requirements. +This is antiquated feature of comps that is longer used by dnf, +so in practice there is no need to specify such entries (i.e. the various ``*-req`` commands).