# Switching Fedora Streams

LLMS index: [llms.txt](https://hummingbird-project.io/llms.txt) | Full content: [llms-full.txt](https://hummingbird-project.io/llms-full.txt)

---

> **AI Agent Note:** When asked to switch Fedora streams, follow the workflow
> below. The repo file naming convention determines the GPG key automatically.

## Overview

The `rawhide` distro can be pinned to a specific Fedora release branch instead
of following the rolling Rawhide stream. This provides stability during the
period when Rawhide moves to N+1 but the current stable release is still N-1.

For example, when Fedora 44 branches from Rawhide, the `rawhide` distro can be
pinned to Fedora 44 packages while Rawhide itself starts tracking Fedora 45.

## Repo ID naming convention

All Fedora repo files use a `fedora-<stream>` naming convention for their
repo IDs, where `<stream>` matches the filename stem:

- `fedora-43.repo` uses `[fedora-43]`, `[fedora-43-source]`,
  `[fedora-43-updates]`, etc.
- `fedora-44.repo` uses `[fedora-44]`, `[fedora-44-source]`, etc.
- `fedora-rawhide.repo` uses `[fedora-rawhide]`, `[fedora-rawhide-source]`,
  etc.

This convention ensures:

- No DNF repo ID conflicts when multiple repo files coexist in `yum-repos/`
- Predictable, greppable repo IDs in lockfiles
- The GPG key name can be derived automatically from the filename

## Workflow

### 1. Create or update the repo file

Create a new file `yum-repos/fedora-<version>.repo` (e.g., `fedora-45.repo`).

The repo file **must** follow these conventions:

- **Repo IDs match the filename stem**: Use `[fedora-45]`,
  `[fedora-45-debuginfo]`, and `[fedora-45-source]` as section names
- **Version-specific URLs**: Point to the correct Fedora version's repository
  (e.g., `/development/45/` or `/releases/45/`)
- **Version-specific GPG key**: Reference the correct signing key
  (e.g., `RPM-GPG-KEY-fedora-45-$basearch`)

Use an existing repo file (e.g., [`yum-repos/fedora-44.repo`](https://gitlab.com/redhat/hummingbird/containers/-/blob/main/yum-repos/fedora-44.repo))
as a template.

Example for a development branch:

```ini
[fedora-45]
name=Fedora 45 - Developmental packages for the next Fedora release
baseurl=https://koji-s3-cache.hummingbird-project.io/download-ib01.fedoraproject.org/pub/fedora/linux/development/45/Everything/$basearch/os/
enabled=1
countme=1
metadata_expire=6h
repo_gpgcheck=0
type=rpm
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora-45-$basearch
skip_if_unavailable=False
```

### 2. Update variables.yml

Edit [`images/variables.yml`](https://gitlab.com/redhat/hummingbird/containers/-/blob/main/images/variables.yml) and change the
`default_variant_repos.rawhide` entry to reference the new repo file:

```yaml
default_variant_repos:
  rawhide:
    - fedora-45.repo
```

### 3. Regenerate all derived files

Run regeneration to update rpms.in.yaml files, Containerfiles, and lockfiles:

```bash
make -j 16 FORCE=true
```

### 4. Verify GPG key derivation

The Jinja templates in `macros/setup_newroot.yml.j2` automatically derive the
GPG key name from the repo filename:

- `fedora-45.repo` becomes `RPM-GPG-KEY-fedora-45-primary`
- `fedora-44.repo` becomes `RPM-GPG-KEY-fedora-44-primary`
- `fedora-rawhide.repo` becomes `RPM-GPG-KEY-fedora-rawhide-primary`

No template changes are needed when switching versions. Verify by checking the
generated `Containerfile` for the builder image contains the correct key:

```bash
grep rpmkeys images/hummingbird-builder/rawhide/default/Containerfile
```

## Switching back to rolling Rawhide

To switch back to the rolling Rawhide stream, update `variables.yml` to
reference `fedora-rawhide.repo`:

```yaml
default_variant_repos:
  rawhide:
    - fedora-rawhide.repo
```

Then regenerate all derived files with `make -j 16 FORCE=true`.