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 maintains reviewed legal files for published Python wheels and how the preliminary review-oriented legal artifacts are generated and checked.

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 changes can be reviewed with small, focused diffs.

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

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 legal payload shipped in the Python wheel via project.license-files.

Today that payload is maintained separately from the preliminary review output 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.

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 wheel legal payload 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 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.

Wheel packaging

The Python wheel includes only the final legal payload, not the whole preliminary review directory.

The current wheel includes:

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

If the final legal payload layout changes, update both the wheel legal-file configuration and this document in the same change.