Cannot scaffold and build an extension that supports only Trixie

[rmoreas]

Summary

It is currently not possible to reliably create and run an extension that supports only the Trixie distro in this repository workflow.

Scaffolding can generate metadata with only Trixie, but the build pipeline still evaluates both Bookworm and Trixie by default, which causes bake/e2e failures when Bookworm package entries are intentionally absent.

Context

I would like to add a new extension where PostgreSQL 18 packages are available only on Trixie (not on Bookworm). This is a valid scenario, but current defaults and file-merging behavior in bake make it fail.

Reproduction

1. Scaffold a new extension with Trixie only.
2. Ensure metadata versions contain only Trixie entries.
3. Run full local flow:
   • task e2e:test:full TARGET=

Actual result

Bake fails during matrix evaluation with an invalid index / missing key error when trying to access package data for Bookworm.

[bake-rdkit] rdkit/metadata.hcl:109
[bake-rdkit] --------------------
[bake-rdkit]  107 |     
[bake-rdkit]  108 |     target "default" {
[bake-rdkit]  109 | >>>   name = "${metadata.name}-${sanitize(getExtensionVersion(distro, pgVersion))}-${pgVersion}-${distro}"
[bake-rdkit]  110 |       matrix = {
[bake-rdkit]  111 |         pgVersion = pgVersions
[bake-rdkit] --------------------
[bake-rdkit] ERROR: rdkit/metadata.hcl:109,39-59: Error in function call; Call to function "getExtensionVersion" failed: docker-bake.hcl:128,48-68: Error in function call; Call to function "getExtensionPackage" failed: docker-bake.hcl:114,29-37: Invalid index; The given key does not identify an element in this collection value: string required, but have tuple..., and 1 other diagnostic(s)

Expected result

If an extension is explicitly single-distro (Trixie only), bake and e2e should run successfully without requiring dummy Bookworm entries.

Root cause

There are two coupled issues:

1. Global distro defaults in the shared bake configuration (docker-bake.hcl)

   • The shared bake config defines distributions with Bookworm + Trixie by default.
   • Matrix expansion therefore includes Bookworm unless explicitly overridden.

2. File merge precedence in bake inputs

   • In the workflow and task commands, file order determines which variable definitions win.
   • When metadata is loaded before the shared bake file, extension-level variable overrides (like distributions) do not take effect.
   • This makes single-distro metadata ineffective unless command file order is reversed or a third override file is added.

In short: scaffolding supports single-distro metadata, but build invocation order/defaults can negate it.

Proposed solution

Recommended

1. Standardize bake file order everywhere (CI + local tasks):

   • Load shared bake file first
   • Load extension metadata second

   This allows per-extension variable overrides to work as intended.

2. Allow per-extension distro override in metadata

   • Support variable distributions in extension metadata for single-distro cases such as Trixie-only.

3. Keep e2e and bake behavior consistent

   • Ensure local tasks and reusable workflow use the same bake file ordering and override semantics.

Optional hardening

1. Add validation in scaffolding or CI:
   • If metadata has only one distro, verify bake matrix resolves only that distro.
2. Add docs section:
   • Clarify supported syntax for distros in scaffolding and explain distro override behavior.

Validation criteria

1. An extension scaffolded for Trixie only can be built and tested end-to-end without Bookworm metadata entries.
2. task bake TARGET= and task e2e:test:full TARGET= succeed for single-distro extensions.
3. Reusable workflow build step behaves the same as local task flow.
4. Documentation includes a clear single-distro example and expected behavior.

Notes

This impacts contributors adding new extensions where package availability differs per distro, and currently creates confusion because scaffolding appears to support single-distro but the default bake flow does not.