[feature] Migrate REUSE bulk annotations to inline SPDX headers

[yreyricord]

Scope of the proposal

Governance or process improvement

Most impacted component

Not specific to one component

Problem statement and motivation

The repository is REUSE-compliant via the bulk REUSE.toml manifest landed in #20 . This works, but it is a transitional setup. Files do not show their licence when you open them, paths can drift silently and break coverage, and external auditors expect inline headers as the canonical form.

This issue is the follow-up: add inline SPDX-FileCopyrightText and SPDX-License-Identifier headers to every legacy file, then shrink REUSE.toml to its minimal form (binary assets and LICENSES/** only).

Proposed solution

The reuse CLI provides a single command (reuse annotate) that can stamp every file in the repository in one pass. The whole migration fits in one PR.

Step 1. Install reuse and check out a branch:

pipx install reuse
git checkout -b chore/reuse-inline-headers

Step 2. Stamp every textual file (95% of the repository, ESA / Apache-2.0):

git ls-files \
  | grep -vE '\.(png|jpg|jpeg|gif|ico|pdf|svg)$' \
  | grep -v '^LICENSES/' \
  | xargs reuse annotate \
      --copyright "European Space Agency (ESA)" \
      --license "Apache-2.0" \
      --year 2026 \
      --merge-copyrights \
      --skip-existing \
      --skip-unrecognised

Flags explained:

• --skip-existing makes the command idempotent: files already carrying a header are left untouched.
• --skip-unrecognised ignores extensions reuse does not know how to comment, instead of failing the whole batch.
• --merge-copyrights adds the new year to an existing copyright line rather than replacing it.

Step 3. Handle third-party files separately:

# IERS bulletin
reuse annotate \
  --copyright "International Earth Rotation and Reference Systems Service (IERS)" \
  --license "CC-BY-4.0" --year 2026 \
  bps-l1_processor/bps/l1_processor/resources/bulletinb-348.txt
OGC and external schemas (licence to be confirmed by ESA)
reuse annotate 

--copyright "Open Geospatial Consortium (OGC) and contributors" 

--license "CC-BY-4.0" --year 2026 

xsd/biomass-xsd/eop.xsd xsd/biomass-xsd/sar.xsd xsd/biomass-xsd/bio-l1-vrt.xsd

Step 4. Stamp binary assets with .license companion files:

git ls-files \
  | grep -E '\.(png|jpg|jpeg|gif|ico|pdf|svg)$' \
  | xargs reuse annotate \
      --copyright "European Space Agency (ESA)" \
      --license "Apache-2.0" --year 2026 \
      --force-dot-license

Step 5. Shrink REUSE.toml to its minimal form:

version = 1
[[annotations]]

path = ["/*.png", "/.jpg", "**/.svg", "**/*.pdf", ...]

SPDX-FileCopyrightText = "2026 European Space Agency (ESA)"

SPDX-License-Identifier = "Apache-2.0"
[[annotations]]

path = ["LICENSES/**"]

SPDX-License-Identifier = "CC0-1.0"

Step 6. Verify and commit:

reuse lint   # must report: project is REUSE-compliant
git add -A
git commit -s -m "chore(reuse): add inline SPDX headers to legacy files"
git push -u origin chore/reuse-inline-headers
gh pr create --base develop

Alternatives considered

No response

Expected impact

Dimension	Impact
Backward compatibility	None. Headers are additive.
Diff size	Large (~270 files modified), but mechanical (one header added at the top of each).
Validation	reuse lint returns zero error after the PR.
Long-term	REUSE.toml shrinks from ~14 annotation blocks to 2. Future renames cannot break licensing coverage.

Additional context

The OGC and external schemas (eop.xsd, sar.xsd, bio-l1-vrt.xsd) are stamped with a provisional declaration in step 3. ESA should confirm the actual licence before this PR is merged. If different, edit the corresponding lines.

Pre-submission checklist

• I have searched existing issues and discussions for a similar proposal.
• I have read the contributing guidelines and the project governance.
• I am available to discuss the design before any implementation starts.