Версионирование набора данных: схема, история, DOI версий
Набор данных меняется: находятся ошибки, добавляются наблюдения, уточняются переменные. Без версий невозможно понять, какой файл использовался в статье и почему цифры в двух публикациях расходятся.
Версионирование — это не про идеальную чистоту, а про возможность ответить на вопрос «что именно вы анализировали».
Зачем нужны версии
Первая причина — воспроизводимость: статья должна ссылаться на конкретное состояние данных.
Вторая — доверие: если ошибка исправлена, пользователи должны знать, чем отличается новая версия от старой.
Нумерация
Удобно использовать семантическую схему: MAJOR.MINOR.PATCH.
MAJOR меняется при несовместимых изменениях: удалены переменные, изменилась структура. MINOR — при добавлении данных или новых переменных без нарушения совместимости. PATCH — при исправлении ошибок в значениях.
Даже если вы не следуете формально SemVer, зафиксируйте правило и придерживайтесь его.
Что считать несовместимым изменением
Удаление колонки, переименование переменной, смена единиц измерения и перекодировка категорий ломают существующие скрипты.
Добавление новых строк обычно совместимо, но меняет результаты расчётов. Это стоит отметить отдельно, даже если версия MINOR.
История изменений
Ведите файл CHANGELOG с датой, номером версии и перечнем изменений. Формулировки должны быть конкретными: «исправлены 12 значений возраста, ошибочно записанных в месяцах».
Общая фраза «мелкие правки» бесполезна: пользователь не поймёт, затрагивает ли это его анализ.
DOI версий
Многие репозитории присваивают DOI каждой версии и отдельный концептуальный DOI для всего набора.
В статье указывайте DOI версии. Концептуальный DOI удобен для общей ссылки, но не фиксирует состояние данных.
Хранение старых версий
Старые версии не удаляйте. Их отсутствие делает невозможной проверку опубликованных результатов.
Если репозиторий не хранит версии, ведите архив самостоятельно и описывайте его в README.
Миграция скриптов
При несовместимом изменении опишите, как перевести старый код: какие переменные переименованы, какие функции заменить.
Хорошая практика — приложить скрипт миграции или таблицу соответствия.
Согласование с соавторами
Изменение данных после подачи статьи в журнал — деликатный вопрос. Если правка влияет на результаты, сообщите редактору.
Скрытая замена файла без пояснений создаёт риск, что проверяющий получит другие числа.
Что писать в статье
Укажите версию набора и DOI. Если использовалась промежуточная версия, отметьте это: читатель должен понимать, что финальная может отличаться.
Для повторного анализа полезно указать дату выгрузки данных.
Частые ошибки
- отсутствие номеров версий;
- удаление старых версий;
- расплывчатый CHANGELOG;
- смена переменных без миграции;
- ссылка на «последнюю версию»;
- замена данных после публикации без уведомления;
- хранение версий только на локальном диске.
Как связать версии с коммитами
Если данные ведутся в системе контроля версий, укажите тег или хеш коммита, соответствующий релизу.
Это позволяет восстановить точное состояние файлов, даже если репозиторий изменился.
Что делать с промежуточными версиями
Не публикуйте каждую правку. Релиз делайте, когда набор пригоден для использования.
Промежуточные состояния нужны внутри команды, но не читателю.
Что делать с исправлениями в тексте
Правки описания не меняют данные и не требуют новой MAJOR-версии, но историю изменений обновить стоит.
Если правка касается смысла переменной, это уже не совместимое изменение.
Как сообщать об изменениях
Для небольших проектов достаточно письма соавторам и записи в CHANGELOG. Для публичных наборов — уведомление в репозитории.
Пользователи должны узнать об изменении до того, как обнаружат расхождение.
Как оформлять релиз
Релиз включает: тег или номер версии, CHANGELOG, обновлённые README и codebook, контрольные суммы.
Проверьте, что все файлы относятся к одной версии: смешение версий — частая ошибка при ручной сборке.
Как поступать с экспериментальными файлами
Черновики и промежуточные выгрузки не публикуйте вместе с релизом. Держите их в отдельной папке.
Читатель должен видеть набор, а не рабочий стол исследователя.
Как согласовать версию с препринтом
Если препринт ссылается на набор, укажите версию. После обновления данных обновите и препринт, если площадка это позволяет.
Расхождение между препринтом и текущей версией — частая причина вопросов.
Итог: простая схема для небольшого проекта
Нумеруйте версии как 1.0, 1.1, 2.0, ведите CHANGELOG и храните старые файлы.
Даже такая простая схема снимает вопрос «какая версия использовалась в статье».
Что делать при слиянии наборов
Слияние — несовместимое изменение: структура и число строк меняются. Это MAJOR-версия.
Опишите, какие наборы объединены, по какому ключу и что произошло с несовпадающими записями.
Чек-лист
- Схема нумерации определена.
- Несовместимые изменения помечены.
- CHANGELOG ведётся.
- Старые версии сохранены.
- DOI версии указан.
- Миграция описана.
- Соавторы уведомлены об изменениях.
Частые вопросы
Нужны ли версии, если данные не меняются?
Достаточно одной версии, но правило нумерации всё равно полезно: изменения появятся.
Как поступить при обнаружении ошибки после публикации?
Выпустите новую версию, опишите ошибку и, если возможно, уведомите журнал и читателей.
Можно ли переименовать набор?
Лучше сохранить прежнее название и добавить уточнение. Новое имя разрывает связь с цитированиями.
Где хранить историю версий?
В репозитории, если он поддерживает версии. Иначе — архив с описанием и контрольными суммами.