Pulp RPM Developer Docs

# Pulp RPM Developer Notes This document's goal is to gather useful information for the pulp_rpm developer. [toc] ## Braindump > Put any notes here if you don't want to think about where it should go. * [pbrochad] I've been thinking about --- ## Onboarding > Notes tailored for onboarding a new developer Hello there! This guide will walk you through some basic concepts, practices and tools of trade for surviving in this wild RPM world. In particular, we'll cover how all the mess we see in the wild relates to how Pulp understand and responds to different requirements and constraints of managing, fetching and distributing RPM content. --- ## Hot Topics ### Package Location re-design ### Checksums Management ### Filter Package on sync ### Handle package conflicts on repositories ### Advisory caveats ### Package Signing: Data Tracking ### Package Signing: Sign existing packages --- ## Troubleshooting > Known troubleshooting quirks and patterns of the RPM ecosystem ### Sync: Server Misconfigurations Some cases which boil down to server misconfiguration: * case: --- ## Reference Gentle introductions to different RPM topics with a curated set of references. ### Rpm Versioning RPM packages versions are defined by an EVR schema (epoch, version, release). This versioning has an intricate set of sorting rules. **Epoch** is used when, for example,a package changes its versioning scheme which would result in newer versions sorting lower than the older ones (e.g, a change between semver and calver). A concrete example is left as an exercise to the reader. **Version** is based on the upstream versioning scheme, if any. There are some special characters and rules here that enables a package to "fix" an upstream versioning which doesn't sort as RPM expects. **Release** is the downstream (packager) versioning scheme. Usually it's a positive integer, but it couldnt be that simple, could it? Special cases for this one too. * [fedora versioning docs] - A guide with examples of different versioning scenarios * [rpmdev-vercmp] - Utility tool that compares RPM versions ### Clients / Package Managers The clients are the primary users of RPM repositories, which means a lot of design/behavior decisions in Pulp RPM are based on what these expect from an rpm repository. There are two main rpm clients out there, dnf and zypper. **Dnf** is the successor for yum for RHEL-based systems, and in some cases yum became an alias to dnf. Not sure if we should count yum as a different client. **Zypper** is one for the Suse distribution. * [dnf] - Default client for RedHat-based distros * Version 5 has signifcant changes from <5 and is called dnf5 * See [dnf5-docs] and [dnf-docs] * [dnf .repo file] - The repository's configuration at the client's machine. * Usually at `/etc/yum.repos.d/` on rpm-based systems * [yum] - Legacy client for RedHat-based distros * Usually shimmed to dnf * [zypper (suse)] - Suse's package manager. ### RPM Package * NEVRA * Advanced discussions: - [RPM microarchitecture] - RPM supports micro-architecture feature levels - The architecture can show in the NEVRA arch. E.g: `x86_64_v4` ### Modularity Modularity is not longer supported in Fedora >=39 and is planned for being dropped from RHEL as well. * Modular Package - A package is considered modular if both are true: * it has a `modularitylabel` flag in the rpm header (set in build time) * it is listed in a modular metadata file (modules.yaml) * [fedora modularity docs] - Core concepts of modularity * [modulemd-tools] - Guides for creating modular repositories * [libmodule-module-stream] - Yaml spec for module stream (from libmodule) * Example repositories: * https://fixtures.pulpproject.org/rpm-modular/ ### Types of Repository * Regular Repository vs Kickstart Repository ### Kickstart Repository * [treeinfo 1.1 format] - Productmd reference on treeinfo 1.1 ### RPM Metadata * Introduction to RPM metadata structure: - [rpm metadata suse-spec] - [rpm metadata schemas] * Canonical vs Custom metadata - TODO ### Metadata: primary.xml * TODO ### Metadata: other.xml * TODO ### Metadata: comps.xml * TODO ### Metadata: updateinfo.xml (advisory) * [updateinfo (suse)] - Schema for the updateinfo.xml file for zypper ---  [updateinfo (suse)]: https://en.opensuse.org/openSUSE:Standards_Rpm_Metadata_UpdateInfo [zypper (suse)]: https://documentation.suse.com/smart/systems-management/html/concept-zypper/index.html [rpm metadata schemas]: https://github.com/rpm-software-management/rpm-metadata [rpm metadata suse-spec]: https://en.opensuse.org/openSUSE:Standards_Rpm_Metadata#Specification [rpm microarchitecture]: https://www.phoronix.com/news/RPM-x86_64-Feature-Levels [fedora modularity docs]: https://docs.fedoraproject.org/en-US/modularity/core-concepts/ [treeinfo 1.1 format]: https://productmd.readthedocs.io/en/latest/treeinfo-1.1.html [dnf .repo file]: https://dnf.readthedocs.io/en/latest/conf_ref.html [fedora versioning docs]: https://docs.fedoraproject.org/en-US/packaging-guidelines/Versioning/ [rpmdev-vercmp]: https://packages.fedoraproject.org/pkgs/rpmdevtools/rpmdevtools/index.html [modulemd-tools]: https://github.com/rpm-software-management/modulemd-tools/blob/d35e773d64a0b00b0f1bbf97cd9bf7eed75a9d30/README-DETAILED.md [libmodule-module-stream]: https://github.com/fedora-modularity/libmodulemd/blob/main/yaml_specs/modulemd_stream_v2.yaml [dnf5-docs]: https://dnf5.readthedocs.io/en/latest/ [dnf-docs]: https://dnf.readthedocs.io/en/latest/