SPDX и REUSE: воспроизводимая разметка небольшого репозитория

SPDX и REUSE помогают превратить разрозненные сведения о происхождении файлов и условиях их использования в проверяемую структуру репозитория. Они полезны только после того, как уполномоченный владелец прав принял решение и команда честно установила происхождение материалов. Разметка не создаёт права, которых нет, не превращает чужой файл в собственный и не заменяет разбор совместимости условий. Практический результат внедрения — возможность для каждого файла показать зафиксированные сведения о правообладателе и лицензии, а затем автоматически найти пропуски в этой разметке.

Сначала инвентаризация, затем идентификаторы

Начинать с массовой вставки заголовков опасно: одинаковая строка может ошибочно приписать команде стороннее изображение, скопированный фрагмент или сгенерированный артефакт. Сначала составьте перечень файлов и разделите их хотя бы по происхождению: созданные участниками проекта, полученные от сторонних авторов, сгенерированные инструментами и файлы с пока неясной историей. Для каждой позиции запишите, откуда она появилась, кто может подтвердить это происхождение, какое разрешение уже дано и кто вправе принять решение о лицензировании.

Неизвестное происхождение — не повод подобрать удобный идентификатор. Такой файл остаётся отдельным вопросом до подтверждения. Для стороннего материала сохраняют его действительное авторство и условия, а не заголовок проекта по умолчанию. Для сгенерированного файла фиксируют, что он сгенерирован, чем и из каких входов; его нельзя автоматически объявлять произведением команды только потому, что он лежит в её репозитории.

Что именно даёт SPDX

SPDX задаёт стандартизированный способ представлять сведения о компонентах и лицензиях. В небольшом репозитории наиболее заметная часть — точные идентификаторы лицензий и выражения из них. Идентификатор обозначает конкретную запись списка, но сам по себе не отвечает, вправе ли проект применять эту лицензию и подходит ли она к остальным условиям распространения.

Как читать AND, OR и WITH

• AND означает, что к обозначенному материалу одновременно относятся несколько наборов лицензионных условий.
• OR означает предусмотренный выбор между указанными вариантами. Такой выбор должен существовать в реальных условиях, а не появляться ради прохождения проверки.
• WITH связывает лицензию с конкретным исключением. Название исключения также должно быть точным и соответствовать записи списка.

Выражение записывают ровно так, как следует из принятого решения и имеющихся разрешений. Нельзя заменять сложную ситуацию приблизительной формулой, смешивать идентификаторы по памяти или считать, что синтаксически корректная строка доказывает совместимость лицензий. Если правообладатель ещё не определил условия, техническая разметка должна подождать этого решения.

Полные тексты в каталоге LICENSES

Короткий идентификатор не заменяет полный текст лицензии. В корне репозитория создают каталог LICENSES и помещают туда точные тексты всех лицензий, на которые ссылаются файловые метаданные. Имена файлов связывают с выбранными идентификаторами последовательно, чтобы инструмент мог сопоставить обозначение и текст. Текст берут из надёжной записи соответствующей лицензии, не пересказывают своими словами и не собирают из случайных фрагментов.

Перед добавлением проверьте, что текст относится именно к тому идентификатору и редакции, которые используются в файлах. Наличие похожего названия недостаточно. Если применяется выражение с несколькими лицензиями, в каталоге должны находиться полные тексты всех упомянутых лицензий; для конструкции WITH отдельно учитывают указанное исключение в той форме, которую предусматривает список.

Метаданные REUSE и три способа покрыть файл

REUSE связывает каждый файл с двумя видами сведений: авторским правообладателем и лицензией. Для этого применяют три способа. Они решают одну задачу, но подходят разным форматам и не должны использоваться как повод менять содержимое файлов без необходимости.

1. Заголовок внутри файла

В текстовый исходник добавляют строки в допустимом для его формата комментарии. Минимальная запись обычно содержит обозначение правообладателя и выражение лицензии:

SPDX-FileCopyrightText: год и корректное обозначение правообладателя

SPDX-License-Identifier: точный идентификатор или выражение

Форма комментария зависит от языка и формата. После вставки нужно убедиться, что файл остаётся корректным и что строка описывает именно его, а не весь каталог по предположению. Не следует помещать заголовок внутрь бинарного файла, ломать машинный формат или редактировать результат генерации, который будет перезаписан при следующем запуске.

2. Соседний файл с окончанием .license

Для изображения, двоичного объекта, неудобного машинного формата или артефакта, который нельзя безопасно менять, создают соседний файл метаданных. Его имя повторяет полное имя исходного файла и получает окончание .license. В нём размещают те же сведения о правообладателе и лицензии. Такой способ сохраняет исходный объект неизменным и делает связь явной на уровне имени.

Соседний файл не исправляет неопределённое происхождение. Перед его созданием всё равно требуется установить, кому принадлежит материал и на каких условиях он оказался в проекте. Для стороннего объекта указывают стороннего правообладателя, если именно это подтверждено; название команды нельзя подставлять автоматически.

3. Узкое правило в REUSE.toml

Когда группа файлов действительно имеет одинаковые подтверждённые условия, сведения можно задать правилом в REUSE.toml. Шаблон должен быть настолько узким, чтобы охватывать только проверенную группу. Общее правило на весь каталог удобно технически, но может незаметно захватить чужие, сгенерированные или позднее добавленные файлы.

Для каждого правила зафиксируйте причину объединения файлов и проверьте список совпадений. Если в каталог поступают материалы из разных источников, предпочтительнее отдельные заголовки или соседние файлы. Правило не должно скрывать различия в авторстве и лицензиях ради более короткой конфигурации.

Воспроизводимый порядок внедрения

1. Зафиксируйте проверяемое состояние: точный commit, ветку при необходимости, наличие локальных изменений и непроиндексированных файлов.
2. Составьте инвентарь всех отслеживаемых и значимых локальных файлов с их происхождением: собственные, сторонние, сгенерированные или неустановленные.
3. Передайте вопрос об условиях тому, кто вправе решать от имени соответствующего правообладателя. Не выбирайте лицензию техническим большинством или по удобству инструмента.
4. Запишите точные SPDX-идентификаторы и выражения, не подменяя неизвестность предположением.
5. Добавьте в LICENSES полные тексты всех указанных лицензий и предусмотренные выражениями исключения.
6. Покройте каждый файл подходящим способом: внутренним заголовком, соседним .license или узким правилом REUSE.toml.
7. Отдельно просмотрите сторонние и сгенерированные материалы, чтобы метаданные не приписывали их вашей команде.
8. Запустите команду проверки в зафиксированном состоянии репозитория.

reuse lint

Для повторяемости запишите версию спецификации REUSE, версию применённой командной программы, версию SPDX, точный commit и сведения о локальном состоянии. Если проверка выполнялась не в чистой копии, перечислите относящиеся к ней изменения. Это позволяет понять, почему поздний запуск на другом наборе файлов дал иной результат.

Как интерпретировать lint

Успешный lint означает, что инструмент не обнаружил предусмотренных им нарушений разметки в проверенном состоянии и при зафиксированной версии. Это полезный технический сигнал, но не заключение о праве собственности, подлинности указанного авторства, достаточности разрешения, совместимости нескольких лицензий или полноте состава репозитория. Ошибочно размеченный файл может выглядеть формально покрытым.

Неуспешная проверка обычно требует локализовать непокрытые файлы, отсутствующие тексты или неоднозначные метаданные, затем исправить сведения и повторить запуск. Если проблема состоит не в формате, а в неизвестном правообладателе или спорных условиях, её нельзя устранить подбором строки. Такой случай возвращают владельцу прав или специалисту, который уполномочен оценивать правовую ситуацию.

Зависимости проверяют отдельным процессом

REUSE-разметка репозитория не равна аудиту зависимостей. Внешние пакеты, вложенный сторонний код и другие компоненты рассматривают отдельно: фиксируют используемые версии и состав, сохраняют относящиеся к распространению уведомления и тексты лицензий, проверяют условия прямых и включённых компонентов. Заголовок вашего проекта не добавляют в чужой код только ради единообразия.

Итоговая процедура поэтому состоит из двух связанных, но разных контуров. Первый отвечает на вопрос, покрыты ли файлы репозитория заявленными метаданными. Второй проверяет происхождение и условия внешних компонентов. Только явное разделение не позволяет превратить зелёный результат lint в обещание полного лицензионного аудита.

Контрольный список перед фиксацией результата

• для каждого файла записано происхождение, а неизвестные случаи не замаскированы;
• решение о лицензировании принято уполномоченным владельцем прав;
• идентификаторы и выражения точны, а полные тексты находятся в LICENSES;
• файлы покрыты заголовками, соседними .license или проверенными узкими правилами;
• сторонние и сгенерированные материалы не приписаны команде;
• lint запущен для зафиксированного commit и понятного локального состояния;
• версии спецификации, SPDX и командной программы сохранены;
• зависимости и вложенные сторонние компоненты вынесены в отдельный аудит.

Ценность такой системы не в значке успешной проверки, а в прослеживаемости. Для каждого файла должно быть возможно восстановить, откуда он взялся, чьё решение отражает лицензия, каким способом записаны метаданные и в каком состоянии репозитория это было проверено.