IMPORTANT: Developer documentation for the current development branch. This content is unreleased, may change without notice, and must not be treated as Buildish release documentation.

Release-legal maintenance workflow

This document explains how the repository generates review-oriented legal artifacts, which files are checked in, and which files are copied into the site pipeline container image.

dist-release-legal/preliminary/

This directory is machine-generated by:

  • make release-legal-preliminary

It contains only the checked-in top-level preliminary drafts:

  • generated LICENSE
  • generated NOTICE

These files are checked into Git so dependency bumps can be reviewed with small, focused diffs.

This directory contains the larger generated review bundle and stays ignored by Git from the repository root.

It contains:

  • inventory.json
  • inventory.md
  • copied bundled third-party legal texts under licenses/ and notices/

This keeps the tracked preliminary directory small without losing the richer generated review data.

This directory contains the final image legal payload that is copied into the container image build.

Today that payload is maintained manually and includes:

  • dist-release-legal/LICENSE
  • dist-release-legal/NOTICE

What the generator actually inspects

The generator derives the runtime dependency set from uv.lock via uv export --format pylock.toml --no-dev --frozen and then inspects the Python distributions available to the current interpreter.

That means the preliminary output is based on the installed Python runtime dependencies, not on a generic package index view.

Container base-image licenses are intentionally not added to the generated preliminary LICENSE right now. That path stays disabled until legal review is clear about whether those image-level licenses should be listed there.

The Containerfile is the single source of image versions and digest pins. The curated manifest in tools/site-pipeline-image/legal/base-image-bundles.toml maps image repositories and supported tag patterns to stable legal-file paths. make check rejects unpinned images, unknown repositories, unsupported tags, and missing curated files. Python stays on 3.13-bookworm; Renovate permits digest updates within that baseline. Routine digest and uv version updates need only change the Containerfile.

The PR image job additionally runs tools/helpers/verify_container_image.py inside each built platform image. It compares Python’s installed LICENSE.txt and the uv source release’s LICENSE-APACHE / LICENSE-MIT against the curated texts. The uv scratch image has no license files, so its source release is selected by the Containerfile tag; this is not a verification of the binary’s provenance or all transitive licenses. Network failures fail the job. Changed texts produce a diff for human review; the check never rewrites legal files. The same job exercises the installed CLI with --help, check, and a small build that must stage an authored page. These checks do not decide the final attribution layout.

Why the generated files are intentionally compact

The checked-in preliminary output is designed to be diff-friendly.

It intentionally omits:

  • generation timestamps
  • dependency version lines in the rendered review documents
  • machine-specific absolute paths from the inventory output

The goal is to surface legal changes, not unrelated churn.

Normal maintainer workflow

  1. Update dependencies.
  2. Run make release-legal-preliminary.
  3. Review the tracked diff in dist-release-legal/preliminary/.
  4. Review the richer generated inventory under dist/release-legal-preliminary/ when you need the supporting detail.
  5. If the legal review result changes, update dist-release-legal/LICENSE and dist-release-legal/NOTICE accordingly.
  6. Run make check.
  7. Commit both the dependency change and any resulting legal-file updates.

What make check verifies

make check regenerates the tracked preliminary LICENSE / NOTICE drafts into a temporary directory and diffs them against dist-release-legal/preliminary/.

This makes CI fail when:

  • metadata changes affect the generated preliminary LICENSE / NOTICE
  • the checked-in preliminary artifacts were not refreshed after dependency work
  • a container image falls outside the curated manifest’s supported repositories or tags, lacks a digest pin, or references missing curated legal files

The supporting inventory bundle under dist/release-legal-preliminary/ is still regenerated by make release-legal-preliminary, but it is not compared as a checked-in artifact.

Container-image packaging

The site-pipeline image build copies only the final legal payload, not the whole preliminary review directory.

The current image includes:

  • dist-release-legal/LICENSE
  • dist-release-legal/NOTICE

If the final legal payload layout changes, update both the container build files and this document in the same change.