Підручник: Як стати сумісним з REUSE

Ви читаєте неофіційний переклад оригінальної сторінки.

У цьому посібнику пояснюються основні методи, як зробити програмний проєкт сумісним із REUSE. Вивчивши цей документ ви знатимете як чітко вказати авторські права і ліцензією своїх файлів, і ви зможете перевірити правильність за допомогою допоміжного засобу REUSE.

Зробити ваш проєкт сумісним із REUSE можна виконавши три прості кроки:

  1. Виберіть і вкажіть ліцензії
  2. Додайте інформацію про авторські права та ліцензію до кожного файлу
  3. Підтвердьте відповідність REUSE

Для цього навчання ми припустимо, що каталог вашого проєкту має такий вигляд:

project/
├── img/
│   ├── cat.jpg
│   └── dog.jpg
├── src/
│   └── main.c
├── .gitignore
├── Makefile
└── README.md

Якщо ви хочете відтворити кроки цього посібника на своєму комп’ютері, ви можете клонувати репозиторій прикладів. Гілка noncompliant відповідає структурі вище, а гілка master — успішний результат цього репозиторію.

Для кожного з цих кроків ви спочатку дізнаєтеся, як виконати їх вручну. Однак допоміжний засіб REUSE підтримує більшість завдань, а необхідні команди також будуть перераховані в розділах, що згортаються. Ми рекомендуємо спочатку зрозуміти основний принцип, перш ніж просто виконувати команди інструмента.

1. Виберіть і надайте ліцензії

Перше, що вам потрібно зробити, це обрати ліцензію. У цьому посібнику ми припускаємо, що ви вибрали Загальну публічну ліцензію GNU (GPL) v3.0 або новішу версію. Обравши ліцензію, вам потрібно розмістити ліцензію в каталозі вашого проєкту.

Ви знайдете свою ліцензію в Списку ліцензій SPDX. SPDX — це відкритий стандарт для повідомлення про ліцензії та авторські права. Кожна ліцензія однозначно ідентифікується за допомогою короткої форми Ідентифікатора ліцензії SPDX. Ідентифікатор ліцензії SPDX для вибраної ліцензії — GPL-3.0 або новішої версії.

Ви створюєте каталог LICENSES у кореневому каталозі проєкту, який міститиме всі ліцензії, які використовуються у вашому проєкті. Потім ви завантажуєте свою ліцензію з репозиторію license-list-data і розміщуєте її до каталогу LICENSES. Назва ліцензії має бути ідентифікатором ліцензії SPDX та розширенням файлу (у цьому прикладі GPL-3.0-or-later.txt).

Ви можете ініціалізувати свій проєкт за допомогою reuse init. В інтерактивному діалоговому вікні ви можете визначити певні властивості вашого проєкту, а також одну або кілька ліцензій. Наприкінці ці ліцензії буде автоматично завантажено у правильне місце.

Команда reuse download дає змогу завантажити певну ліцензію. reuse download GPL-3.0-or-later виконає завдання, описане в інструкціях вище. Запуск reuse download --all автоматично завантажує всі ліцензії, які допоміжний засіб REUSE виявляє, якщо вони використовуються у вашому проєкті.

2. Додайте відомості про авторські права та ліцензування до кожного файлу

Тепер, коли у вас є ліцензія, вам потрібно вказати у відповідних файлах, що ці файли підпадають під цю ліцензію. Ви редагуєте заголовок коментаря src/main.c таким чином:

/*
 * SPDX-FileCopyrightText: 2019 Jane Doe <jane@example.com>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 */

Тег SPDX-FileCopyrightText фіксує роки публікації та власника авторських прав на вміст файлу. Читайте докладніше про які роки публікації використовувати і які існують власники авторських прав у поширених запитаннях.

За тегом SPDX-License-Identifier слідує дійсний вираз ліцензії SPDX, як правило, лише ідентифікатор ліцензії SPDX.

Кожен файл завжди повинен містити ці два теги в заголовку. Ви можете використовувати теги кілька разів, якщо у вас є кілька власників авторських прав або ліцензій.

У прикладі проєкту ви також редагуєте Makefile і README.md, використовуючи цю інформацію заголовка, але, звичайно, з відповідним синтаксисом коментарів.

Команда reuse addheader допомагає додавати відомості про ліцензії та авторські права до ваших файлів. Для завдання вище, така команда виконуватиме цю роботу:

reuse addheader --copyright="Jane Doe <jane@example.com>" --license="GPL-3.0-or-later" src/main.c Makefile README.md

Перегляньте документацію засобу про addheader, щоб дізнатися про додаткові опції, як-от стилі коментарів і шаблони

Двійкові та некоментовані файли

Ви також хочете ліцензувати файли зображень під GPL-3.0 або новішої версії. На жаль, зображення та інші двійкові файли не мають заголовків коментарів, які можна легко редагувати. Інші приклади включають автоматично згенеровані файли та певні файли даних та конфігурації, коментарі до яких не нульові.

Існує простий обхідний шлях. Створіть файли cat.jpg.license і dog.jpg.license, кожен з яких містить однакові відомості про ліцензію та власника авторських прав, як зазначено вище.

Допоміжний засіб REUSE повинен автоматично виявити двійкові файли та, отже, автоматично створити відповідний файл .license.

Якщо цього не сталося, або якщо ви хочете примусово застосувати це, додайте аргумент --explicit-license до команди addheader. Отже, команда для вищезазначеного завдання може мати такий вигляд:

reuse addheader --copyright="Jane Doe <jane@example.com>" --license="GPL-3.0-or-later" --explicit-license img/cat.jpg img/dog.jpg

Змінити відомості про ліцензування

Ви дізнаєтесь, що світлини кота та пса були ліцензовані зовсім не за GPL, а за ліцензією Creative Commons Attribution 4.0 International, що належить Максу Мелу.

Ідентифікатор ліцензії SPDX цієї ліцензії — CC-BY-4.0. Ви створюєте файл LICENSES/CC-BY-4.0.txt, дотримуючись тих самих кроків, які використовували для GPL-3.0-or-later.

Потім ви редагуєте cat.jpg.license і dog.jpg.license, щоб сказати:

SPDX-FileCopyrightText: 2019 Max Mehl <max.mehl@fsfe.org>

SPDX-License-Identifier: CC-BY-4.0

Наразі засіб не надає способу заміни наявних відомостей про авторські права та ліцензування, сумісних з REUSE. Запуск команди addheader не замінить, а розширить файли .license двома додатковими рядками із зазначенням авторських прав Макса Мела та ліцензії CC-BY-4.0. Таким чином, вам потрібно оновити їх вручну.

Однак команда download згодом дозволить вам автоматично завантажити нову ліцензію або використавши reuse download CC-BY-4.0, або просто reuse download --all.

Створення технічних файлів

Під час компіляції програми створюються деякі технічні файли збірки, як-от src/main.o. Вам не потрібно вказувати будь-які відомості про ліцензування для цих файлів. Просто використовуйте файл .gitignore, щоб ігнорувати ці технічні файли збірки. Засіб REUSE зважатиме на вміст .gitignore.

Незначні файли

Можливо, у вашому проєкті будуть файли, які ви не вважаєте за потрібне захищати авторським правом, наприклад, файли конфігурації, як-от .gitignore. Швидше за все ви не захочете ліцензувати ці файли, але основна ідея REUSE полягає в тому, що всі ваші файли, очевидно, матимуть зазначені авторські права та ліцензування.

Якщо ви не використовуєте жодних авторських прав на цей файл, ви можете використовувати ліцензію CC0. Це функціонально ідентично розміщенню файлу у відкритому доступі. Відредагуйте файл, щоб він містив:

# SPDX-FileCopyrightText: 2019 Jane Doe <jane@example.com>
#
# SPDX-License-Identifier: CC0-1.0

Отже, вам доведеться надати ліцензію CC0-1.0 в каталозі LICENSES/, так само як раніше GPL-3.0-or-later і CC-BY-4.0.

Докладніше про файли, захищені авторським правом, можна прочитати в розділі ЧАП REUSE.

Як і раніше, комбінація команд addheader and download виконає наведену раніше дію:

reuse addheader --copyright="Jane Doe <jane@example.com>" --license="CC0-1.0" .gitignore

reuse download --all

Результат

Ваше дерево проєкту тепер матиме такий вигляд:

project/
├── img/
│   ├── cat.jpg
│   ├── cat.jpg.license
│   ├── dog.jpg
│   └── dog.jpg.license
├── LICENSES/
│   ├── CC0-1.0.txt
│   ├── CC-BY-4.0.txt
│   └── GPL-3.0-or-later.txt
├── src/
│   └── main.c
├── .gitignore
├── Makefile
└── README.md

3. Підтвердьте відповідність повторного використання

Тепер, коли ви позначили всі файли їхніми авторськими правами та ліцензіями, настав час перевірити, чи нічого ви не пропустили. Для цього ми надаємо вам допоміжний засіб. Ви можете прочитати всю документацію або прочитати про наведені далі дії.

Дотримуйтесь інструкцій з установлення, доступних для кількох платформ. Тепер перейдіть до каталогу проєкту і запустіть лінтер.

$ cd path/to/project/
$ reuse lint
# SUMMARY

* Bad licenses:
* Deprecated licenses:
* Licenses without file extension:
* Missing licenses:
* Unused licenses:
* Used licenses: CC-BY-4.0, CC0-1.0, GPL-3.0-or-later
* Read errors: 0
* Files with copyright information: 6 / 6
* Files with license information: 6 / 6

Congratulations! Your project is compliant with version 3.0 of the REUSE Specification :-)

Як ви можете бачити в останньому рядку, засіб підтверджує, що ваш проєкт тепер сумісний із REUSE! Щоб дізнатися, що означають різні розділи, перегляньте документацію команди lint.

Довідка

Прочитавши через цей посібник, ви зрозуміли як працює REUSE і три основні кроки, щоб правильно ліцензувати ваш програмний проєкт. чудово! Але хоч ми й розглянули кілька випадків, у вас може скоро виникнути більше питань. Але не хвилюйтеся, ми тут, щоб допомогти!:

– Наші Поширені запитання охоплюють типові запитання, а також надзвичайні випадки, і вони постійно оновлюватимуться.

Якщо жодне з наведених посилань не відповідає на ваше запитання, зв’яжіться з нами за допомогою:

  • відкриття обговорення на reuse-docs для запитань щодо посібника, поширених запитань або специфікації;

  • відкриття обговорення на reuse-tool для запитань про засіб REUSE;

  • або надіславши електронного листа до FSFE. Зауважте, що ми надаємо перевагу обговоренням, оскільки вони доступні для загального пошуку для інших людей.

Дякуємо вам за ваш цінний внесок у створення програмного забезпечення для повторного використання!