Document adding and retiring Linux build platforms
A new Debian, Ubuntu, Fedora or EL release is named in seven places across the build matrices, the snapshot and release workflows, the acceptance tests and the publishing wrapper, and missing the wrapper leaves the packages built and uploaded but never indexed. pkg/linux/PLATFORMS.md lists them all, with the steps for adding a platform, retiring one and the server-side follow-up. The platform lists in the Debian and Red Hat READMEs had drifted (Ubuntu 25.04, Fedora 40 and 41, RHEL 8), so they now point at the build matrices instead.
This commit is contained in:
Dave Page
@@ -5,8 +5,9 @@ Debian and Ubuntu.
|
||||
|
||||
## Supported platforms
|
||||
|
||||
* Debian 11, 12 & 13
|
||||
* Ubuntu 22.04, 24.04 & 25.04
|
||||
The platforms built are the ones in the matrix in
|
||||
`.github/workflows/check-deb-build.yml`; see `pkg/linux/PLATFORMS.md` for how
|
||||
to add or retire one.
|
||||
|
||||
## Build configuration
|
||||
|
||||
|
||||
174
pkg/linux/PLATFORMS.md
Normal file
174
pkg/linux/PLATFORMS.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# Adding and retiring Linux platforms
|
||||
|
||||
Debian, Ubuntu, Fedora and EL releases come and go several times a year, and
|
||||
each one is named in more places than is obvious: the build matrices, the
|
||||
staging and release workflows, the acceptance tests and the publishing wrapper
|
||||
on the servers all carry their own list. Missing one does not always fail
|
||||
loudly (a platform the wrapper does not know about is built, uploaded and then
|
||||
quietly left unindexed), so work through the whole of the relevant section
|
||||
below rather than stopping when CI goes green.
|
||||
|
||||
Architectures are a different change, and are not covered here; see the
|
||||
comments on the RPM tree in `.github/workflows/snapshot.yml`, `YUM_TARGETS` in
|
||||
`pkg/publish/pga-publish` and `Architectures` in `pkg/publish/aptftp.conf`.
|
||||
|
||||
## Where platforms are named
|
||||
|
||||
| File | What it holds | Naming |
|
||||
|---|---|---|
|
||||
| `.github/workflows/check-deb-build.yml` | The DEB build matrix, which the snapshot and release candidate workflows call | `debian-13`, `ubuntu-2604`, plus the container image |
|
||||
| `.github/workflows/check-rpm-build.yml` | The RPM build matrix, likewise | `el-10`, `fedora-44`, plus the image and the PGDG repository RPM URL |
|
||||
| `.github/workflows/snapshot.yml` | `codename_for()`, mapping DEB build names to codenames; the `case` mapping RPM build names to repository trees | `ubuntu-2604` to `resolute`; `el-10` to `redhat/rhel-10` |
|
||||
| `.github/workflows/release-candidate.yml` | The same two mappings, duplicated | as above |
|
||||
| `.github/workflows/acceptance-test.yml` | The install test matrices, which add the published repositories and install from them | `resolute`; `rhel-10`, `fedora-44` |
|
||||
| `.github/workflows/promote-release.yml` | The `rebuild-apt` and `rebuild-yum` calls in "Publish the packages" | `resolute`; `redhat rhel 10 x86_64` |
|
||||
| `pkg/publish/pga-publish` | `APT_CODENAMES` and `YUM_TARGETS`, which decide what the servers create, index and promote | as `promote-release.yml` |
|
||||
|
||||
These do not need changing for a new release of an existing distribution:
|
||||
|
||||
* The repository configuration RPMs (`pkg/redhat/repo-rpm.sh`), which use
|
||||
`$releasever` rather than naming versions.
|
||||
* The repository READMEs, whose platform tables `install-repo-readme.py`
|
||||
derives from the trees on disk and the archive bucket.
|
||||
* The DEB and RPM build scripts, unless the new release needs something
|
||||
different; see 'Version-specific code' below.
|
||||
|
||||
## Adding a platform
|
||||
|
||||
### Before starting
|
||||
|
||||
Check that the pieces the build depends on exist for the new release:
|
||||
|
||||
* The container image on Docker Hub (`ubuntu:26.04`, `fedora:45`,
|
||||
`almalinux:11`). New Ubuntu releases usually have a tag some weeks before
|
||||
release; building against a pre-release image is fine for proving the build,
|
||||
but do not publish packages from one.
|
||||
* For RPM platforms, the PGDG repository RPM
|
||||
(`https://download.postgresql.org/pub/repos/yum/reporpms/`), since the build
|
||||
takes `libpq5-devel` and `postgresql18-devel` from PGDG. On EL, EPEL must
|
||||
also exist for the new version. DEB builds use the distribution's own
|
||||
`libpq-dev` and have no equivalent dependency.
|
||||
* The codename, for DEB platforms: it is what `lsb_release -cs` prints and
|
||||
what the repository directory is called, so take it from the release itself
|
||||
rather than from the version number.
|
||||
|
||||
### In this repository
|
||||
|
||||
All of this goes in one pull request. The DEB and RPM checks do not run on
|
||||
pull requests, only on pushes to `master` and on dispatch, so prove the new
|
||||
matrix leg before merging by dispatching `check-deb-build.yml` or
|
||||
`check-rpm-build.yml` against the branch in a fork with Actions enabled
|
||||
(`gh workflow run check-deb-build.yml --ref <branch>`).
|
||||
|
||||
1. Add the matrix leg to `check-deb-build.yml` or `check-rpm-build.yml`,
|
||||
copying the neighbouring entry's form exactly. The `name` becomes part of
|
||||
the artifact name, and the mappings below parse it back out.
|
||||
2. Add the mapping for the new name to `snapshot.yml` and to
|
||||
`release-candidate.yml`. A DEB name with no `codename_for()` entry fails
|
||||
the assemble job with `Unknown Debian build name`; an RPM name that is not
|
||||
`el-*` or `fedora-*` fails with `Unknown RPM build name`.
|
||||
3. Add the platform to both matrices in `acceptance-test.yml`.
|
||||
4. Add the `rebuild-apt` codename, or the `rebuild-yum` line, to "Publish the
|
||||
packages" in `promote-release.yml`.
|
||||
5. Add the codename to `APT_CODENAMES`, or the tuple to `YUM_TARGETS`, in
|
||||
`pkg/publish/pga-publish`. The wrapper refuses to index anything not in
|
||||
these tables, and the snapshot and staging indexers only look for the trees
|
||||
they name, so without this the new packages are uploaded but never indexed,
|
||||
and `packages-fetch` never carries them into the live repository.
|
||||
|
||||
If the build needs a platform-specific change (a package renamed, a new
|
||||
AppArmor rule, a different Python), make it in the same pull request, so that
|
||||
the new matrix leg proves it.
|
||||
|
||||
### On the servers
|
||||
|
||||
`pga-publish` and the scripts beside it are installed by hand on both the
|
||||
staging and the download servers, as described under "Installing" in
|
||||
`pkg/publish/README.md`. Reinstall them on both once the pull request is
|
||||
merged, and before the next snapshot, since the snapshot and release candidate
|
||||
workflows build the new platform from then on and the servers will skip what
|
||||
their installed copy of the tables does not name.
|
||||
|
||||
### Proving it
|
||||
|
||||
1. Dispatch a publishing snapshot (`gh workflow run snapshot.yml -f
|
||||
publish=true`), and check that the new platform's tree in the snapshot has
|
||||
signed indices (`InRelease` for APT, `repodata/repomd.xml.asc` for YUM), and that
|
||||
the snapshot's README lists it.
|
||||
2. Install from the snapshot on the new platform, following that README.
|
||||
3. The first release candidate's acceptance test installs it from the staging
|
||||
repository, which is the check that matters before promotion.
|
||||
|
||||
### The first release that carries it
|
||||
|
||||
`rebuild-readme` builds the production README's history from the archive
|
||||
bucket, and exits with `<platform> is published but absent from the archive`
|
||||
when a platform in the live tree has never been copied there. Promotion runs
|
||||
`rebuild-readme` in "Publish the packages", before `sync-s3` copies the
|
||||
release to the archive in "Update the website", so the first promotion after
|
||||
adding a platform fails at that point, with the packages already live but the
|
||||
website not updated. Until that ordering is changed, expect it: run
|
||||
`pga-publish sync-s3` by hand on the download server, then rerun
|
||||
`pga-publish rebuild-readme` for the affected kind and finish the website
|
||||
steps.
|
||||
|
||||
### Elsewhere
|
||||
|
||||
The download pages on www.pgadmin.org list the supported platforms, and live
|
||||
outside this repository. Open an issue for the platform, too, so that the
|
||||
pre-release pass picks it up for the release notes, as with `Issue #9263`
|
||||
("Added Ubuntu 25.10 and Fedora 43") in `release_notes_9_11.rst`.
|
||||
|
||||
## Retiring a platform
|
||||
|
||||
A platform is retired when it stops receiving builds. Its repository keeps
|
||||
serving the last packages it had until somebody removes the tree, and the
|
||||
archive bucket keeps them after that, since `sync-s3` never deletes.
|
||||
|
||||
### In this repository
|
||||
|
||||
Reverse steps 1 to 5 of adding a platform, in a single pull request: the
|
||||
matrix leg, both mappings, both acceptance test entries, the promotion
|
||||
`rebuild-*` line and the wrapper table entry. Then remove any version-specific
|
||||
code that only existed for that platform (see below).
|
||||
|
||||
Keep the steps together. A platform removed from the wrapper tables but still
|
||||
in the build matrices is built and uploaded, then silently left out of the
|
||||
indices and the promotion.
|
||||
|
||||
Reinstall the wrapper on both servers once it is merged, as when adding one.
|
||||
|
||||
### On the download server
|
||||
|
||||
Nothing is removed automatically, and the production README will go on
|
||||
listing the platform as supported for as long as its tree holds packages,
|
||||
since it takes the supported list from the trees that exist. To move it to the
|
||||
"no longer supported" table:
|
||||
|
||||
1. Make sure the archive bucket has the platform's last release, which it will
|
||||
if `sync-s3` has run since that release was promoted.
|
||||
2. Remove the tree from the live repository: `apt/<codename>` for APT, or
|
||||
`yum/<family>/<name>-<version>-<arch>` and its `Server`, `Workstation` and
|
||||
`Client` compatibility links for YUM.
|
||||
3. Run `pga-publish rebuild-readme apt` or `yum`.
|
||||
|
||||
When to do this is a policy decision rather than a mechanical one: users who
|
||||
have not upgraded their distribution lose `apt update`/`dnf update` access to
|
||||
pgAdmin the moment the tree goes.
|
||||
|
||||
## Version-specific code
|
||||
|
||||
The build scripts branch on the distribution version in a few places. Check
|
||||
them when adding a platform, and delete the dead branches when retiring one:
|
||||
|
||||
* `pkg/debian/build.sh`: the AppArmor profile and `postinst` for Ubuntu 24 and
|
||||
later.
|
||||
* `pkg/linux/build-functions.sh`: the EL 8 Python selection, in `_setup_env`
|
||||
and `_copy_code`.
|
||||
* `pkg/redhat/setup.sh` and `pkg/debian/setup.sh`: prerequisites for building
|
||||
by hand. CI does not run these (the workflows install their own), so they
|
||||
are the likeliest to be out of date; `pkg/redhat/setup.sh`, for example,
|
||||
only knows EL 8 and 9.
|
||||
* The comments in `check-deb-build.yml` and `check-rpm-build.yml`, which name
|
||||
the releases their workarounds apply to (PEP 668, dnf5, the distribution's
|
||||
Node.js on Ubuntu 26.04).
|
||||
@@ -5,3 +5,6 @@ various Linux distributions.
|
||||
|
||||
You should not use them directly, but the functionality provided can be used to
|
||||
simplify your own build scripts (typically by sourcing *build-functions.sh*).
|
||||
|
||||
Adding or retiring a Linux platform touches more than the build scripts; see
|
||||
*PLATFORMS.md* for everywhere a platform is named.
|
||||
|
||||
@@ -5,10 +5,9 @@ Redhat distributions.
|
||||
|
||||
## Supported platforms
|
||||
|
||||
* Fedora 40 & 41
|
||||
* RHEL 8
|
||||
* Rocky Linux 8 (x86_64)
|
||||
* AlmaLinux/RHEL/Rocky Linux 9 (x86_64)
|
||||
The platforms built are the ones in the matrix in
|
||||
`.github/workflows/check-rpm-build.yml`; see `pkg/linux/PLATFORMS.md` for how
|
||||
to add or retire one.
|
||||
|
||||
## Build configuration
|
||||
|
||||
|
||||
Reference in New Issue
Block a user