Skip to content

Commit 61332b1

Browse files
committed
DOC: Document SBOM and SPDX tooling in Utilities/Maintenance
Adds a section to Utilities/Maintenance/README.md describing the five SBOM-related Python scripts added in this PR: * AddSPDXHeaders.py - migration script + pre-commit enforcement * VerifySPDXVersions.py - UpdateFromUpstream cross-check * ValidateSBOMLight.py - in-tree lightweight validator * ValidateSBOMWithSpdxTools.py - spdx-tools reference validator * ComputeSBOMFingerprint.py - drift detection Describes the typical workflows (add headers, verify versions, validate SBOM, baseline fingerprint) so maintainers can use the tooling without reading each script individually. Cross-references the companion assets: Utilities/KWStyle/ITKHeader.h template, REUSE.toml, LICENSES/ directory.
1 parent 22f2b47 commit 61332b1

File tree

1 file changed

+54
-0
lines changed

1 file changed

+54
-0
lines changed

Utilities/Maintenance/README.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,57 @@ Note that the files in this directory are not tested automatically
88
by the continuous integration (CI) of the ITK git repository. So a
99
git commit that only modifies files in this directory should not
1010
trigger a run of the CI.
11+
12+
## SBOM and SPDX Tooling
13+
14+
The following scripts support ITK's SPDX-2.3 Software Bill of Materials
15+
workflow (see `CMake/ITKSBOMGeneration.cmake` and
16+
`CMake/ITKSBOMValidation.cmake`). All require Python 3.10 or later.
17+
18+
| Script | Purpose |
19+
|--------|---------|
20+
| `AddSPDXHeaders.py` | Prepend SPDX-FileCopyrightText / SPDX-License-Identifier lines to ITK-owned source files. Idempotent; skips files that already carry an SPDX header. Used by the `check-spdx-headers` pre-commit hook with `--check --files <paths>` to enforce SPDX on new files. Handles shebangs, UTF-8 BOM, and CRLF line endings safely. |
21+
| `VerifySPDXVersions.py` | Cross-check that each ThirdParty module's `SPDX_VERSION` in `itk-module.cmake` matches the tag declared in its `UpdateFromUpstream.sh`. Skips modules tracking `master`, commit SHAs, or ITK-custom `for/*` tags. Invoked by CTest as `ITKSBOMVersionConsistency`. |
22+
| `ValidateSBOMLight.py` | In-tree lightweight validator for the generated SBOM. Checks required SPDX 2.3 fields, license-reference integrity, and SPDXID uniqueness. Always runs via CTest `ITKSBOMValidation`. |
23+
| `ValidateSBOMWithSpdxTools.py` | Full SPDX 2.3 schema validation via the optional `spdx-tools` pip package. Returns CTest skip code 77 when `spdx-tools` is not installed so the test is optional rather than a hard dependency. Invoked by CTest as `ITKSBOMSchemaValidation`. |
24+
| `ComputeSBOMFingerprint.py` | SHA-256 fingerprint over the sorted, canonicalized SBOM package metadata (name, version, license, PURL). Used for drift detection between branches and in CI via CTest `ITKSBOMFingerprint` when `ITK_SBOM_FINGERPRINT_BASELINE` is set. |
25+
26+
### Typical workflows
27+
28+
Add SPDX headers to new files:
29+
```
30+
python3 Utilities/Maintenance/AddSPDXHeaders.py <source-tree>
31+
```
32+
33+
Verify SBOM matches upstream versions:
34+
```
35+
python3 Utilities/Maintenance/VerifySPDXVersions.py .
36+
```
37+
38+
Validate a generated SBOM:
39+
```
40+
python3 Utilities/Maintenance/ValidateSBOMLight.py build/sbom.spdx.json
41+
# For full schema validation (pip install spdx-tools first):
42+
python3 Utilities/Maintenance/ValidateSBOMWithSpdxTools.py build/sbom.spdx.json
43+
```
44+
45+
Track SBOM changes:
46+
```
47+
# Baseline the current state:
48+
python3 Utilities/Maintenance/ComputeSBOMFingerprint.py build/sbom.spdx.json \
49+
--compare Utilities/Maintenance/sbom-fingerprint.baseline --update
50+
51+
# Later, verify no drift:
52+
python3 Utilities/Maintenance/ComputeSBOMFingerprint.py build/sbom.spdx.json \
53+
--compare Utilities/Maintenance/sbom-fingerprint.baseline
54+
```
55+
56+
### Related files
57+
58+
- `Utilities/KWStyle/ITKHeader.h` — canonical ITK file header template,
59+
enforced by the KWStyle CTest. Starts with the two SPDX lines followed
60+
by the Apache-2.0 notice block.
61+
- `REUSE.toml` (repo root) — REUSE 3.x blanket license annotations for
62+
ITK-owned files that do not carry per-file SPDX headers.
63+
- `LICENSES/` (repo root) — canonical SPDX license texts required by
64+
REUSE 3.x.

0 commit comments

Comments
 (0)