ADR-0004: Move private_product into package metadata
- Status: Accepted
- Authors: Prarit Bhargava
- Jira: HUM-11758
- Date: 2026-11-05
- Accepted: 2026-11-18
- Last updated: 2026-11-19
This record relocates the design approved in infrastructure!1979. The decision is unchanged.
Summary
This ADR moves the per-package private_product setting out of
ci/package-overrides.yaml in the rpms repository and into the package
metadata JSON (metadata/<package>.json). It also requires that every read,
write, and validation of private_product is implemented in the core library,
hum.meta, and that the CI scripts that use the value go through that library
instead of parsing YAML or JSON themselves.
The RPM metadata and versioning specification defines the authoritative metadata contract. This ADR records the decision and rationale for extending it.
Motivation
private_product routes a package to a private, per-product Pulp repository
(for example nodejs20) instead of the public one. A private product groups
packages for publication to access-restricted repositories. Today the setting
is stored in ci/package-overrides.yaml, which is a build-configuration file,
not package metadata. This causes the following problems:
- Implicit classification. Because the setting is not part of the package
metadata, other tooling tends to infer private or long-term-support (LTS)
status from the package name, for example a
-ltssuffix. A name is not a reliable signal: an upstream project can legitimately have a name that ends in-ltswithout being an LTS package. Routing and classification must be driven by explicit data, never by naming conventions. - Split source of truth. Everything else about a package (origin, version,
modification status, upstream tracking) lives in
metadata/<package>.jsonand is handled byhum.meta.private_productis the exception, so a reader has to consult two files to understand one package. - Duplicated file handling.
ci/generate_resources.py,ci/check_nevr_conflicts.py, andci/dist_git.pyeach read or editpackage-overrides.yamldirectly.dist_git.add_private_product()edits the file line by line to preserve formatting. This is the kind of direct file manipulation thathum.metaexists to replace, and it is not covered by the library’s validation.
Depends on
- ADR-0003: RPM metadata and versioning adopts the metadata specification that this ADR extends.
- HUM-6232 ported the metadata consumers onto
hum.meta.
Impacts
User facing
None for external users. Packages continue to be built and published to the
same repositories. Maintainers set private_product in the package’s metadata
JSON instead of package-overrides.yaml.
Repositories
- documentation/
- gorget/
- rpms/
- containers/
- infrastructure/
- skills/
- tools/ (CI, Website)
rpms/ holds the metadata, the library, and all affected scripts.
documentation/ holds this ADR and the metadata specification.
infrastructure/ removes the original design document in favor of this ADR.
Decision
1. Metadata field
Add an optional private_product field to metadata/<package>.json:
- Type: string. When absent, the package is public.
- The value is the product name and must match the
private_productof an entry inci/konflux_rpa_config.yml. - The field is valid in every metadata state; it is orthogonal to the clean, modified, and independent states.
- The
private_productkey inci/konflux_rpa_config.ymlis a property of the RPA entry, not of a package. It is unchanged by this ADR.
2. Core library changes (hum.meta)
All handling of the field is implemented in hum.meta. No script may read or
write private_product by parsing a metadata or overrides file directly.
hum.meta.model: addprivate_product: str | NonetoPackageMetadataand the concrete subclasses, with a validated setter and JSON round-tripping.hum.meta.validation: validate the value (non-empty string, allowed character set). Check that it matches an RPA entry inci/konflux_rpa_config.yml; this check moves out ofgenerate_resources.py.hum.meta.repository: provide the read and write paths. Setting the field is aload, set,saveoperation onMetadataRepository, which replaces the line-based YAML edit.- Queries: provide library helpers to enumerate packages by product
(
{package: private_product}and the inverse) so consumers do not scan files. - Tests in
hum/meta/tests/cover the field, its validation, and the repository round trip.
3. Consumers
Each consumer switches to the library:
| File | Change |
|---|---|
ci/generate_resources.py |
Use the library for per-package product lookup and the RPA cross-check. Public RPAs still exclude packages that have a product. |
ci/check_nevr_conflicts.py |
Replace load_private_products() with a library query. Behavior is unchanged. |
ci/dist_git.py |
add_private_product() sets the field through MetadataRepository instead of editing package-overrides.yaml. It still adds the RPA entry in konflux_rpa_config.yml. |
The private_product documentation block in ci/package-overrides.yaml is
removed once no entries remain.
4. Migration
Existing entries (nodejs20 and the example entry) are moved into the
matching metadata/<package>.json files in the same MR that ports the
consumers, so the data and the code change together. This follows the pattern
used for HUM-6232. A one-time script is acceptable, but it is not kept in the
repository afterwards. During the migration, no package may have the field in
both places.
Risks and open questions
- Schema change process. Metadata changes require an ADR and a corresponding specification update. Review and approve this ADR with the specification update before merging any implementation MRs.
- Two-file consistency. A package’s product and the RPA entry live in different files. The library validation in section 2 is the guard against drift. The open question is whether the RPA entry should also move into metadata in a later ADR.
- Allowed characters. The allowed character set for product names still needs to be defined.
- Other readers of the overrides file. Scripts outside
rpms/ciand documentation may refer toprivate_productinpackage-overrides.yaml. The implementation MR must search for these before the key is removed.
Implementation notes
- Implementation is tracked in HUM-13038.
- Land the library change (
hum.meta, with tests) first, then the consumer and migration MR, then the operating documentation updates. - Documentation to update in
rpms/:documentation/operating/private-rpm-repositories.md,documentation/operating/package-metadata-fields.md, anddocumentation/background/rpm-pipeline.md. - Update the tests in
test/test_generate_resources.py,test/test_check_nevr_conflicts.py, andtest/test_dist_git.pyto build their fixtures from metadata JSON instead ofpackage-overrides.yaml. - When the implementation is complete, a follow-up MR changes this ADR’s status to Implemented.