maintaining-oss-state

# Maintaining FlashDreams's OSS state FlashDreams is released to the public under Apache-2.0 (OSRB Bug [6107043](https://nvbugswb.nvidia.com/NVBugs5/redir.aspx?url=/6107043)). The repo carries a fixed set of collateral that the OSRB approved on, and a `reuse-lint` CI workflow that fails the build if that collateral drifts. This skill is the map for keeping the collateral consistent — what each file is for, what edits trigger which downstream paperwork, and which CI gates catch what. > The reference design here was landed across PRs #54 (CONTRIBUTING.md), > #55 (Apache-2.0 collateral), #111 (cudaraster + LodePNG disclosure), > #119 (strict inline SPDX CI), and the `alpadreams → omnidreams` rename > (#128 / #132). The git history of those commits is the canonical > example for every operation described below. ## TL;DR - **Six files at repo root + one CI workflow define OSS state:** `LICENSE`, `LICENSES/`, `NOTICE`, `THIRD-PARTY-NOTICES`, `REUSE.toml`, `CONTRIBUTING.md`, and `.github/workflows/reuse-lint.yml`. Touch any of them with the same care you'd give to a public API. - **`LICENSE` has a multi-license preamble** explaining that the bulk of the repo is Apache-2.0 and that two subtrees (cudaraster → BSD-3-Clause, LodePNG → Zlib) carry different OSI licenses, then reproduces the full Apache-2.0 text. CI verifies the canonical Apache-2.0 sentinel strings are present; the structural cross-references in the preamble are not lint-checked (these files change rarely — see the change-log review path instead). - **`NOTICE` is the minimal Apache 2.0 §4(d) notice** — NVIDIA copyright + pointers to `LICENSE`, `LICENSES/`, and `THIRD-PARTY-NOTICES`. It is *not* the full attribution document. - **`THIRD-PARTY-NOTICES` is the full per-dependency attribution document** — direct runtime deps, reference architectures, optional integrations, and source-level redistributions, each with SPDX identifier and upstream URL. - **Every first-party source file carries an inline SPDX header.** `REUSE.toml`'s `**` aggregate keeps the lint green for files that can't carry one (config, assets, binaries), but `reuse-lint`'s "Inline SPDX headers on first-party source files" step rejects any new `.py` / `.c` / `.cpp` / `.cu` / `.sh` / `.proto` / `Dockerfile` / etc. without the inline tag. - **Direct deps are mirrored in three places:** the workspace member's `pyproject.toml` `dependencies`, the resolved `uv.lock` pin, and the `THIRD-PARTY-NOTICES` "Direct runtime dependencies" table. All three must agree. - **Third-party source physically present in the repo** (cudaraster, LodePNG) lives in `THIRD-PARTY-NOTICES` "Source-level redistributions", carries the full license text under `LICENSES/<SPDX>.txt`, has a matching `REUSE.toml` `override` annotation, and is cross-referenced from the `LICENSE` preamble. - **OSRB Bug 6107043 §14 is the source of truth for which deps are "covered" by the contribution approval.** Adding a new direct dep = reopen 6107043 and amend §14. Adding a transitive that only matters because the SBOM scanner flagged it = either reopen + amend §14, or file a self-cert under `osrb/`. Dev-only transitives → SBOM correction (not shipped). ## 1. The OSS-collateral file set | File / path | Role | OSRB anchor | |---|---|---| | `LICENSE` | Multi-license preamble (Apache-2.0 + BSD-3 + Zlib pointer) followed by the canonical Apache-2.0 v2.0 text. CI verifies the canonical Apache-2.0 sentinel strings are present (preamble structure is not lint-gated). | 6107043 item #3 + OSRB unified-posture review | | `LICENSES/Apache-2.0.txt` | REUSE 3.3 license-bundle copy of the canonical Apache-2.0 text (no preamble — must remain reusable verbatim by REUSE tooling). | 6107043 item #3 | | `LICENSES/BSD-3-Clause.txt` | Full BSD-3 text covering the in-source cudaraster port. | 6107043 Cmt #5 (2) | | `LICENSES/Zlib.txt` | Full Zlib text covering the embedded LodePNG codec. | 6107043 Cmt #5 (2) | | `NOTICE` | Apache 2.0 §4(d) minimal notice — NVIDIA copyright + pointers to `LICENSE`, `LICENSES/`, and `THIRD-PARTY-NOTICES`. Carried forward verbatim by downstream redistributions. | Apache-2.0 §4(d) | | `THIRD-PARTY-NOTICES` | Full per-dependency attribution: Direct runtime deps + Reference architectures + Optional-integration deps + Source-level redistributions. The source of truth for the third-party manifest. | OSRB review (canonical attribution doc) | | `REUSE.toml` | REUSE 3.3 aggregate / override annotations for files without inline SPDX. | 6107043 item #2 | | `CONTRIBUTING.md` | Apache-2.0-only contribution statement + DCO v1.1 reproduction + "Signing Your Work" subsection (with `git commit -s` and `--signoff`) + IP-review reference. | 6107043 item #6 + OSRB DCO template | | `.github/workflows/reuse-lint.yml` | CI gate enforcing REUSE 3.3 compliance, presence of the five core OSRB collateral files (`LICENSE`, `LICENSES/Apache-2.0.txt`, `CONTRIBUTING.md`, `NOTICE`, `REUSE.toml`), canonical Apache-2.0 text in `LICENSE` and `LICENSES/Apache-2.0.txt`, `CONTRIBUTING.md` DCO/sign-off reference, inline SPDX headers (incl. `.sh` / `.proto` / Dockerfile), and no legacy proprietary banners. Content-shape of `LICENSE` preamble / `CONTRIBUTING.md` policy text / `THIRD-PARTY-NOTICES` sections is reviewed manually, not lint-checked. | (enforces the above) | The CI workflow runs on every PR, every push to `main`, and inside the GitHub merge queue. A failed `reuse-lint` blocks merge — never bypass it, fix the underlying file. ## 2. Per-file SPDX headers Every first-party source file starts with a concise two-line SPDX header. The `reuse-lint` "Inline SPDX headers on first-party source files" step checks for `SPDX-License-Identifier` in the first 20 lines. It does not check `SPDX-FileCopyrightText` or require a non-empty tag value; the separate REUSE job validates repository-wide copyright and license coverage. **Python / shell / TOML / YAML** (`#` line comments): ```python # SPDX-FileCopyrightText: Copyright (c) <YEAR> NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 ``` **C / C++ / CUDA** (`//` line comments): use the same two SPDX tags with `//` swapped for `#`. Rules: - `<YEAR>` is the **current calendar year** for newly created files (use the system clock — *not* a model-training-cutoff year). For files being **edited**, leave the year alone — it reflects original authorship, not last-touched. - The two SPDX tags (`SPDX-FileCopyrightText` + `SPDX-License-Identifier`) are the preferred house style. The longer Apache-2.0 boilerplate is accepted but not required. - Use the actual copyright holder for new files. Preserve existing copyright notices when editing a file; multiple copyright lines are allowed. See `CONTRIBUTING.md#coding-conventions`. - The Cosmos-Drive-Dreams files (`integrations_v2/omnidreams/impl/conditioning/world_scenario/{camera_base,ftheta,pinhole}.py`) carry two `SPDX-FileCopyrightText` lines (NVIDIA + Cosmos-Drive-Dreams contributors). Mirror that pattern when redistributing other modified upstream Apache-2.0 source. ### What's exempt (handled by `REUSE.toml`) - Vendored upstream under `integrations_v2/omnidreams/impl/ludus-renderer/ludus_renderer/_cpp/cudaraster/**` (carries its own BSD-3 / Zlib banners; `override` annotation in REUSE.toml). - Binary assets (`assets/**.png`, `.jpg`, `.jpeg`, `.webp`, `.mp4`, `.gif`, `.svg`) and lock files (`uv.lock`). - Documentation (`**.md`, `**.rst`, `docs/**`). If a tracked source file genuinely cannot carry an inline header (a tooling-generated artifact, an asset, a config file), extend `REUSE.toml` rather than fighting the lint. ## 3. `REUSE.toml` — aggregate vs override `REUSE.toml` is the REUSE 3.3 manifest that fills gaps the inline SPDX header convention can't. Precedence rules (from `REUSE.toml`): - **`precedence = "aggregate"`** — declared license merges with any inline SPDX header the file carries. Used for the project-wide default (`path = "**"` → Apache-2.0) and for documentation / config / build / asset blocks. - **`precedence = "override"`** — declared license replaces any inline SPDX header. Used for vendored upstream (`cudaraster/**` → BSD-3-Clause; `lodepng/**` → Zlib) to keep the upstream banners authoritative while still surfacing the SPDX identifier REUSE needs. When to add an annotation block: | Scenario | Block style | precedence | |---|---|---| | Add a new first-party source-file type covered by the default `**` rule | (nothing — default covers it) | n/a | | Add a new asset / config / generated-output path that can't carry an inline header | new `[[annotations]]` block, copyright + Apache-2.0 | `aggregate` | | Add a new third-party source subtree (different license, banners we want to keep) | new `[[annotations]]` block, copyright = upstream, SPDX = upstream's license | `override` | | Add a redistributed-and-modified upstream Apache-2.0 file | new block listing dual `SPDX-FileCopyrightText` (NVIDIA + upstream) | `aggregate` | More specific paths win — the cudaraster `override` covers everything under that subtree, then the lodepng `override` overrides the cudaraster block for the lodepng leaf. Order the annotations so specific paths come *after* general ones. ## 4. `NOTICE` vs `THIRD-PARTY-NOTICES` — what goes where Two distinct files. Mixing them up is the most common OSS-state mistake. ### `NOTICE` — minimal, downstream-propagated `NOTICE` exists to satisfy **Apache 2.0 §4(d)**: any derivative work must carry a readable copy of the upstream `NOTICE` text. Keep it small so downstream consumers do not pay an unreasonable carry-forward cost. Shape: ``` NVIDIA FlashDreams Copyright (c) <YEAR> NVIDIA CORPORATION & AFFILIATES. All rights reserved. This product is licensed under the Apache License, Version 2.0; the full license text is reproduced in LICENSE at the repository root and in LICENSES/Apache-2.0.txt. Two subtrees physically vendored into this repository carry different OSI-approved licenses; full texts are reproduced under LICENSES/: - integrations_v2/omnidreams/impl/ludus-renderer/ludus_renderer/_cpp/cudaraster/ BSD-3-Clause (see LICENSES/BSD-3-Clause.txt) - integrations_v2/omnidreams/impl/ludus-renderer/ludus_renderer/_cpp/ cudaraster/framework/3rdparty/lodepng/{lodepng.h,lodepng.cpp} Zlib (see LICENSES/Zlib.txt) Third-party software attributions, source-level redistribution disclosures, and the full per-dependency license inventory are documented in THIRD-PARTY-NOTICES at the repository root. ``` Do not enumerate transitive dependencies, SPDX tables, or per-package attributions in `NOTICE`. Those go in `THIRD-PARTY-NOTICES`. ### `THIRD-PARTY-NOTICES` — full per-dependency manifest `THIRD-PARTY-NOTICES` is the consumer-facing attribution document and the source of truth for the third-party manifest. It has four named sections; do not invent new ones without a corresponding `REUSE.toml` change. ``` NVIDIA FlashDreams — Third-Party Notices Copyright (c) <YEAR> NVIDIA CORPORATION & AFFILIATES. All rights reserved. Preamble explaining the dynamic-import / no-source-redistribution default and pointing readers at the Source-level redistributions section at the bottom. ================================================================================ Direct runtime dependencies ================================================================================ <name> <SPDX> <upstream-URL> ... one row per direct dep ... ================================================================================ Reference architectures ================================================================================ Wan 2.1 / Wan 2.2 Apache-2.0 https://github.com/Wan-Video/Wan2.1 <one paragraph explaining the reference-architecture relationship and confirming weights/sources aren't redistributed> ================================================================================ Optional integration: integrations/<name> ================================================================================ <one block per integration that pulls in deps not used by the root package — currently omnidreams (mediapy, opencv-python-headless, shapely, ludus-renderer) and lingbot (aiohttp, aiortc, opencv-python-headless)>