Політика версіювання даних Мета: забезпечити відтворюваність і прозорість змін даних/метаданих/коду у публікаціях і репозиторіях (DataverseUA, Zenodo, Figshare, Dryad, Git).
Охоплення: усі артефакти набору: data (raw/interim/processed), metadata, code, docs.
-----------------------------------------
1) Схема версій
Використовуємо SemVer
Код: Виділити все
MAJOR.MINOR.PATCH- MAJOR (1.0 → 2.0): несумісні зміни структури/смислу (нові змінні, інші одиниці, перерахунок, що змінює висновки).
- MINOR (1.1 → 1.2): додано нові партії/рядки/файли без ламання сумісності; невеликі поліпшення.
- PATCH (1.2.0 → 1.2.1): дрібні виправлення (описів, орфографії, метаданих) без зміни числового змісту.
• Dataverse: цитуємо DOI набору + Version X.Y.
• Zenodo/Figshare/Dryad: цитуємо Version DOI (конкретна версія); за потреби додаємо Concept DOI (усі версії).
-----------------------------------------
2) Хто за що відповідає (RACI)
Код: Виділити все
Завдання | R (виконує) | A (відповідає) | C (консультує)
---------------------------------+-------------+----------------+---------------
Опис змін (CHANGELOG) | Дослідник | Дата-стюард | ІТ
Перевірка метаданих/FAIR | Дата-стюард | Дата-стюард | Дослідник
Публікація/версія у сховищі | Дата-стюард | PI/Кер.проєкту | ІТ
CI/автоматизація, токени, бекапи | ІТ | ІТ | Стюард
3) Мінімум для кожного релізу
Код: Виділити все
[ ] Оновлено номер версії (vX.Y[.Z]) у описі набору
[ ] Заповнено metadata/CHANGELOG.md (Added/Changed/Fixed/Removed/Deprecated)
[ ] Оновлено metadata/file_manifest.csv (role, derived_from, checksum)
[ ] Оновлено metadata/data_dictionary.csv (якщо змінювались змінні/одиниці)
[ ] README.md коротко описує, як відтворити processed з raw
[ ] Ліцензія + спосіб цитування (CITATION або інструкція)
4) Що саме версіонуємо
- Data: raw/interim/processed (чітко позначати роль у маніфесті).
- Metadata: опис набору, теги, RelatedIdentifiers, словник змінних.
- Code: скрипти конвеєра; реліз коду синхронізовано з версією даних (за можливості).
- Docs: методики, протоколи, журнали змін; ідентичні до опису у сховищі.
5) Коли збільшувати версію
- Зміна структури колонок/одиниць → MAJOR
- Додавання нових файлів/рядків, що не ламає сумісність → MINOR
- Виправлення описів/опечаток/метаданих → PATCH
6) Цитування та DOI
- У публікаціях вказуйте конкретну версію (Version DOI або DOI + Version X.Y).
- Якщо raw опубліковані окремо — дайте перехресні посилання (RelatedIdentifier: IsDerivedFrom).
- Для обмежених/чутливих raw: публікуйте processed + інструкцію доступу/запиту до raw.
7) Іменування та структура
Коротко: ISO-дати, snake_case/kebab-case, в processed додавайте
Код: Виділити все
_vX.YРекомендована структура:
Код: Виділити все
data/{raw,interim,processed}/, code/, docs/, metadata/(README, CHANGELOG, file_manifest.csv, data_dictionary.csv, relationships.csv)
8) Автоматизація (рекомендовано)
- CI копіює текст з metadata/CHANGELOG.md у опис чернетки версії перед публікацією.
- Скрипт перевіряє наявність checksum і узгодженість маніфесту з реальною структурою.
9) Винятки та зняття з публікації
- Помилкові дані з ризиком для користувачів: позначити як Deprecated у новій версії; попередні версії не видаляємо, а маркуємо.
- Персональні/чутливі дані: публікуємо тільки знеособлені або в контрольованому доступі; будь-які зміни змісту → принаймні MINOR, часто MAJOR.
1) Шаблон CHANGELOG.md
Код: Виділити все
# Changelog
У форматі Keep a Changelog. Дати у ISO: YYYY-MM-DD. Версіювання: SemVer MAJOR.MINOR.PATCH.
## [1.2.0] – 2025-08-15
### Added
- (нові файли/змінні/функції)
### Changed
- (що змінилося без ламання сумісності)
### Fixed
- (виправлення)
### Removed / Deprecated
- (вилучено або позначено як застаріле)
## [1.1.0] – 2025-07-20
### Added
- Приклад попередньої версії
2) Як вставляти release notes у DataverseUA вручну
- Відкрийте набір → Edit → Metadata.
- У Citation Metadata знайдіть поле Description і вставте коротке резюме, напр.:
Release notes v1.2 (2025-08-15): Added daily aggregates; fixed unit kPa→MPa. - Збережіть зміни. Додайте файл metadata/CHANGELOG.md на вкладці Files (мітка Documentation).
- Після перевірки — Publish (minor/major).
3) CI: копіювання changelog у опис чернетки (GitHub Actions)
Код: Виділити все
# .github/workflows/dataverse-changelog.yml
name: Dataverse Changelog Sync
on:
workflow_dispatch:
inputs:
dataset_pid:
description: 'doi:10.5072/FK2/ABCDEFG'
required: true
release_type:
description: 'minor/major'
default: 'minor'
publish:
description: 'Publish after update? true/false'
default: 'false'
env:
DATAVERSE_BASE_URL: ${{ secrets.DATAVERSE_BASE_URL }}
DATAVERSE_API_TOKEN: ${{ secrets.DATAVERSE_API_TOKEN }}
CHANGELOG_PATH: metadata/CHANGELOG.md
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: '3.10' }
- run: |
python -m pip install --upgrade pip
pip install requests pydataverse
- name: Push changelog
env:
DATASET_PERSISTENT_ID: ${{ inputs.dataset_pid }}
RELEASE_TYPE: ${{ inputs.release_type }}
PUBLISH: ${{ inputs.publish }}
run: python .github/scripts/push_changelog.py