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 exact image references that contribute files to the final image are still checked against the curated manifest in tools/site-pipeline-image/legal/base-image-bundles.toml. make check fails when a referenced image lacks current curated metadata or its legal files are missing. This freshness check does 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
  • the container definition and curated base-image legal manifest drift apart

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.