Модуль 7. Практикум

В модуле 4 мы свели требования открытой науки к тринадцати категориям артефактов. Практикум превращает этот перечень в последовательность действий: каждый шаг добавляет к коду один или несколько артефактов, и в конце на месте «папки со скриптами» оказывается полноценный программный объект – версионированный, лицензированный, документированный, заархивированный и цитируемый.

Маршрут универсален, но глубина прохождения зависит от типа ПО (модуль 3). Для большинства объектов C4 базовым будет маршрут до шага 7 включительно. Нужны ли сверх этого тесты, фиксация окружения и контейнер, определяет не только тип: одноразовый скрипт может оказаться единственным средством проверки ключевого результата, и тогда решающими оказываются доказательная значимость кода, хрупкость его окружения и ожидаемое повторное использование. Предметному ПО C3 нужны и продвинутые шаги (тесты, иногда контейнер). Собственному или институционально сопровождаемому инфраструктурному ПО C1–C2 нужен полный маршрут, включая рецензирование и работу с сообществом. Для внешних компонентов уровня C1 маршрут неприменим: по ним достаточно зафиксировать версию, идентификатор и зависимости. На каждом шаге отдельно отмечена роль библиотекаря: где он дает шаблон, где консультирует, где настраивает институциональную интеграцию.

Команды в практикуме приведены для системы контроля версий Git и даются с пояснениями; от читателя не требуется опыта программирования, но полезно иметь доступ к командной строке и учетную запись на платформе GitHub или GitLab.

Контроль версий – фундамент всего остального: без истории изменений невозможны ни версионирование, ни корректное цитирование. Git фиксирует каждое изменение кода как «снимок» (коммит), а публичный хостинг (GitHub, GitLab) делает репозиторий доступным.

Базовая последовательность для нового проекта:

git init -b main               # создать репозиторий, ветка main
git add README.md src/         # добавить файлы ЯВНО, не «git add .»
git diff --cached              # проверить, что именно попало в индекс
git commit -m "Первый коммит"  # зафиксировать снимок
git remote add origin <URL>    # привязать созданный на хостинге репозиторий
git push -u origin main        # выгрузить на хостинг

До того, как создавать репозиторий, проводят инвентаризацию папки: убирают персональные и конфиденциальные данные, пароли, токены и ключи доступа, локальные настройки, крупные массивы данных и промежуточные результаты, а также проверяют, есть ли право публиковать каждый компонент. Затем создают файл .gitignore, куда вносят все, что не должно попасть в репозиторий. Порядок здесь принципиален: команда «git add .» забирает вообще все содержимое папки, а .gitignore, созданный после коммита, уже ничего не удаляет из истории – удалять придется переписыванием истории, и при утечке ключа его в любом случае нужно сначала отозвать и заменить. Поэтому в учебной инструкции файлы добавляют явным перечислением и перед коммитом сверяют индекс командой «git diff —cached». Удаленный репозиторий предварительно создают на хостинге – команда «git remote add» лишь привязывает к нему локальную папку. Это типичная точка, где нужна помощь библиотекаря: проверить, что в открытый доступ не уходят персональные данные.

Роль библиотекаря: объяснить смысл контроля версий, провести инвентаризацию папки до первого коммита, помочь с .gitignore, предостеречь от публикации чувствительных данных.

Без лицензии код нельзя законно использовать: по умолчанию все права сохраняются за автором. Лицензия – это разрешение, которое автор дает остальным. Для исследовательского кода применяют лицензии, одобренные Open Source Initiative (OSI), которые делятся на два больших семейства.

Прежде чем выбирать лицензию, необходимо установить, кто вправе ее предоставить. Автор кода не всегда является правообладателем: по статье 1295 Гражданского кодекса исключительное право на служебное произведение принадлежит работодателю, если трудовым или гражданско-правовым договором не предусмотрено иное. Картину меняют также условия гранта или договора подряда и лицензии заимствованных компонентов. Поэтому до публикации проверяют: кто правообладатель; что говорят трудовой договор, договор с заказчиком и условия гранта; под какими лицензиями распространяются использованные библиотеки и совместимы ли они с выбранной; нет ли в коде и данных конфиденциальных сведений, персональных данных или патентоспособных решений. Отсутствие коммерческого интереса само по себе права распоряжаться кодом не дает. Библиотека может объяснить варианты и проверить метаданные, но спорные случаи передает юридической службе или подразделению по трансферу технологий.

• Разрешительные (permissive): MIT, BSD, Apache-2.0. Позволяют почти любое использование, в том числе встраивание в закрытые продукты, при условии сохранения уведомления об авторстве. Apache-2.0 дополнительно явно регулирует патентные права.
• Копилефт (copyleft): GPL, LGPL, MPL, AGPL. Требуют, чтобы производные произведения сохраняли открытость. Сильный копилефт (GPL) распространяет требование на весь производный продукт; слабый (LGPL, MPL) – лишь на саму библиотеку или измененные файлы, допуская связывание с закрытым кодом. AGPL добавляет условие для сетевого взаимодействия: если пользователи работают с измененной версией программы по сети, им должен быть предложен исходный код именно этой версии. Открывать весь сервис целиком лицензия не требует.

Выбор между семействами – содержательное решение: разрешительная лицензия максимизирует распространение, копилефт защищает открытость производных. Подобрать лицензию помогает сервис choosealicense.com. Выбранный текст помещают в файл LICENSE в корне репозитория, а в метаданных указывают стандартный идентификатор SPDX (например, MIT, Apache-2.0, GPL-3.0-or-later). Памятка по выбору лицензии приведена в приложении Б.

Роль библиотекаря: проверить вместе с исследователем, установлен ли правообладатель, проконсультировать по выбору семейства лицензий, обратить внимание на лицензии зависимостей, помочь оформить файл LICENSE, а спорные правовые случаи передать юристу. В российском контексте (модуль 6) – пояснить, как открытая лицензия сочетается с регистрацией РИД.

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

1. Что это – название и одно-два предложения о назначении.
2. Установка – как развернуть код и его зависимости.
3. Использование – минимальный рабочий пример.
4. Как цитировать – ссылка на идентификатор и файл цитирования.
5. Лицензия – указание лицензии.
6. Контакты и вклад – как связаться и как внести вклад.

Шаблон README приведен в приложении А. Для крупных проектов README дополняют развернутой документацией (Sphinx, MkDocs), но для проектного кода C4 README достаточно.

Роль библиотекаря: дать шаблон README, проверить полноту, помочь сформулировать раздел «как цитировать».

Чтобы код цитировали правильно, в корень репозитория помещают файл CITATION.cff – человеко- и машиночитаемое описание того, как цитировать. Минимальный набор полей:

cff-version: 1.2.0
message: "Если вы используете это ПО, цитируйте его так."
title: "Название программы"
authors:
  - family-names: Иванова
    given-names: Мария
    orcid: "https://orcid.org/0000-0000-0000-0000"
version: 1.0.0
doi: 10.5281/zenodo.0000000
date-released: 2026-05-31
url: "https://github.com/user/repo"
license: MIT

Составить файл помогает веб-инструмент cffinit. Когда CITATION.cff присутствует, GitHub автоматически показывает кнопку «Cite this repository». Для машиночитаемых метаданных дополнительно оформляют codemeta.json (формат CodeMeta, модуль 4) – его удобно создавать специальным веб-генератором или собирать автоматически в конвейере вроде HERMES. Шаблоны обоих файлов приведены в приложении А.

Эти файлы готовят и проверяют до того, как оформлен релиз. Zenodo архивирует именно тот снимок репозитория, который зафиксирован релизом. Интеграция с GitHub может импортировать поддерживаемые поля файла CITATION.cff; если в репозитории есть файл .zenodo.json, Zenodo использует его, а CITATION.cff игнорирует. Файл codemeta.json служит обмену метаданными с другими системами и метаданные записи Zenodo сам по себе не заменяет. Файлы, добавленные после выпуска релиза, в заархивированную версию уже не попадут. Отсюда и кажущийся замкнутый круг с DOI: идентификатор, который нужно указать в CITATION.cff, выдается только при депонировании. Разрешается он одним из двух способов – при ручном депонировании DOI резервируют в Zenodo заранее и вписывают в файл до создания релиза, а при автоматической интеграции с GitHub указывают concept DOI проекта либо вносят полученный DOI в следующую документированную версию.

Роль библиотекаря: помочь составить CITATION.cff и codemeta.json, проверить идентификаторы ORCID и связь с DOI – это работа, прямо соответствующая библиотечной компетенции в метаданных.

Чтобы на код можно было сослаться однозначно, ему нужны версии. Распространенная схема – семантическое версионирование (SemVer) вида MAJOR.MINOR.PATCH. Она предполагает, что у программы объявлен публичный интерфейс (API), относительно которого и определяется совместимость; для разовых скриптов без такого интерфейса довольно даты, тега или идентификатора коммита. Первое число меняется при несовместимых изменениях, второе – при добавлении функций с сохранением совместимости, третье – при исправлениях. Версию фиксируют тегом в Git и оформляют как релиз на хостинге:

git tag -a v1.0.0 -m "Версия 1.0.0"
git push origin v1.0.0

Релиз – это и есть та единица, которой будет присвоен идентификатор на следующем шаге.

Поэтому тег и релиз оформляют, когда в репозитории уже лежит все, что должно попасть в архив: README, файл LICENSE, описание зависимостей, CITATION.cff и, если он используется, codemeta.json.

Роль библиотекаря: объяснить схему версионирования, увязать момент релиза с депонированием.

GitHub – не архив: репозиторий можно удалить или сделать закрытым, и ссылка перестанет работать. Для долгосрочного сохранения и получения постоянного идентификатора код депонируют в архив. Каноническая связка – GitHub и Zenodo.

Порядок действий:

1. Войти в Zenodo с помощью учетной записи GitHub.
2. В списке репозиториев включить переключатель напротив нужного.
3. Создать на GitHub релиз (шаг 6). Zenodo автоматически заберет его, заархивирует и присвоит DOI.

В результате Zenodo выдает два идентификатора: concept DOI на проект в целом (всегда ведет к последней версии) и version DOI на конкретный релиз (модуль 4). Значок DOI добавляют в README, чтобы код был сразу цитируемым. Дополнительно код можно сохранить в Software Heritage напрямую через функцию «Save code now», получив идентификатор SWHID, привязанный к точному состоянию исходника. По другой, кураторской модели депонирование проходит через институциональный или национальный архив с модерацией библиотекаря – как в рабочем процессе французского национального архива HAL, разобранном в модуле 3.

Роль библиотекаря: настроить институциональную интеграцию (в том числе сообщество в Zenodo для организации), провести депонирование вместе с исследователем или по его поручению – при условии, что правообладатель установлен и согласие на публикацию получено, – проверить корректность присвоенных идентификаторов. Это шаг, где помощь библиотеки наиболее ощутима.

Для предметного ПО C3 и инфраструктуры C1–C2 маршрут продолжается. Тесты (например, фреймворк pytest в Python) проверяют, что код работает как задумано; непрерывная интеграция (CI) автоматически прогоняет тесты при каждом изменении – на GitHub это настраивается файлом рабочего процесса в каталоге .github/workflows. Контейнеризация (Docker) упаковывает код вместе с окружением, резко снижая различия между средами и типичную проблему «у меня не запускается»; полной гарантии долговременной воспроизводимости контейнер не дает – он сам зависит от базовых образов, реестров и архитектуры, поэтому вместе с ним сохраняют рецепт сборки (Dockerfile) и сведения о базовом образе; описание окружения хранится в файле Dockerfile. Для интерактивных материалов – например, Jupyter-ноутбуков – сервис Binder (mybinder.org) по файлу зависимостей собирает среду и запускает ноутбук в браузере. Воспроизводимость результата этим не гарантируется: она зависит еще и от данных, внешних сервисов и полноты фиксации окружения.

Роль библиотекаря: для большинства объектов C4 эти шаги избыточны (модуль 4); для C3 и C2 – направить исследователя к команде RSE или к обучающим материалам, а не выполнять работу за него.

Высшая планка – рецензирование самого кода и открытость для сообщества. Зрелый пакет можно подать на рецензирование: в журнал Journal of Open Source Software (JOSS), принимающий пакеты на разных языках, или в rOpenSci – инициативу рецензирования пакетов на R (модуль 5). Подходит для этого не любой «зрелый пакет», и требования стоит проверить заранее: JOSS принимает только открытый код под лицензией, одобренной OSI, с очевидным исследовательским назначением и подтвержденным вкладом, в состоянии функциональной полноты, с документацией и тестами, причем репозиторий должен быть публичным более шести месяцев и показывать непрерывную разработку, а не единичный всплеск коммитов. Одноразовые скрипты и отдельные ноутбуки в этот формат не проходят. У rOpenSci и PyOpenSci свои критерии и своя предметная привязка, поэтому актуальные требования сверяют непосредственно перед подачей. Открытость для вклада обеспечивают файлы CONTRIBUTING.md (как внести вклад) и кодекс поведения (Code of Conduct). Эти артефакты относятся к слою устойчивости и применимы прежде всего к инфраструктуре C1–C2 и зрелому предметному ПО C3.

Роль библиотекаря: информировать о возможности рецензируемой публикации кода, при необходимости – связать исследователя с соответствующим сообществом.

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

Таблица. Сводный маршрут публикации исследовательского ПО

Сквозной пример

Проследим маршрут на одном объекте. Исследовательница подготовила скрипт на Python, который обрабатывает данные опроса и строит графики для статьи, – это типичный проектный код категории C4. Она обращается в библиотеку с вопросом, как сослаться на скрипт в публикации.

Библиотекарь ведет ее по маршруту.

Шаг 1: скрипт уже лежит в папке, его выкладывают в репозиторий на GitHub, предварительно вписав в .gitignore файл с исходными данными опроса, содержащими персональные сведения.

Шаг 2: сначала библиотекарь проверяет права – скрипт написан вне служебного задания, заимствованных компонентов под копилефт-лицензиями в нем нет, ограничений со стороны гранта тоже; убедившись в этом и учитывая, что исследовательница хочет максимально широкого использования, выбирают лицензию MIT и кладут файл LICENSE.

Шаг 3: по шаблону из приложения А составляют README с назначением, инструкцией запуска и примером.

Шаг 4: командой фиксации зависимостей сохраняют список использованных библиотек с версиями в requirements.txt.

Шаг 5: с помощью инструмента cffinit составляют CITATION.cff с идентификатором ORCID автора, оставляя поле DOI до депонирования.

Шаг 6: оформляют релиз v1.0.0 – к этому моменту в репозитории уже лежат README, LICENSE, файл зависимостей и файл цитирования.

Шаг 7: через заранее настроенную библиотекой интеграцию GitHub с Zenodo релиз автоматически архивируется, и Zenodo присваивает version DOI и concept DOI; полученный DOI вносят в CITATION.cff и значок DOI в README при следующей версии.

Шаги 8 и 9 для скрипта C4 пропускают как избыточные (таблица 3.3). В статье теперь можно сослаться на конкретную версию кода по ее DOI; на всю работу у библиотекаря и исследовательницы ушло меньше часа – при заранее заведенных учетных записях, настроенной интеграции с Zenodo и уже проясненных правах на код.

Если бы тот же библиотекарь курировал не скрипт, а развиваемую сообществом библиотеку C2, маршрут прошли бы целиком: добавили бы тесты и непрерывную интеграцию (шаг 8), при необходимости контейнер, а затем подали бы пакет на рецензирование в JOSS (шаг 9). Один и тот же маршрут, разная глубина – логика триажа, которая описана в модулях 3 и 4.

Практикум превращает тринадцать категорий артефактов в маршрут из девяти шагов: контроль версий, лицензия, документация, зависимости, файл цитирования и метаданные, версия и релиз, архивирование с присвоением DOI, тесты и контейнеризация, рецензирование и работа с сообществом. Глубина прохождения зависит от типа ПО: для проектного кода достаточно первых семи шагов, инфраструктуре нужен весь маршрут. На каждом шаге у библиотекаря своя роль – от шаблона и консультации до настройки институциональной интеграции с Zenodo и помощи с метаданными.

Ключевые термины

• Коммит – зафиксированный снимок изменений в Git.
• Разрешительная и копилефт-лицензия – два семейства открытых лицензий: одно максимизирует распространение, другое защищает открытость производных.
• SPDX-идентификатор – стандартное машиночитаемое обозначение лицензии.
• Семантическое версионирование (SemVer) – схема версий MAJOR.MINOR.PATCH; применима при объявленном публичном интерфейсе (API).
• Связка GitHub – Zenodo – способ присвоить релизу кода постоянный DOI.
• Binder – сервис, превращающий ноутбук с файлом зависимостей в запускаемую в браузере среду.

1. Почему контроль версий назван фундаментом всего маршрута?
2. В чем различие разрешительных и копилефт-лицензий и как выбрать между ними?
3. Почему GitHub нельзя считать архивом и как получить для кода постоянный идентификатор?
4. Какие шаги маршрута обязательны для проектного кода C4, а какие нужны только для C3 и C1–C2?

1. Пройдите шаги 1–7 на учебном репозитории (можно с минимальным скриптом): добавьте лицензию, README, файл зависимостей, составьте CITATION.cff, создайте релиз и получите DOI на Zenodo (в песочнице sandbox.zenodo.org).
2. Составьте сценарий двухчасового семинара для исследователей вашей организации по шагам 1–7 с таймингом и раздаточными материалами.
3. Для трех объектов разных типов (C4, C3, C2) определите, до какого шага маршрута их следует довести, и обоснуйте.