Прямой ответ
Каждый опубликованный человеческий текст, схема данных и пакет файлов имеет версию. Отдельно классифицируйте несущественное изменение вроде исправления опечатки, обратно совместимое новое поле или пояснение и ломающую совместимость правку, которая нарушает прежнее поле, правило или поведение потребителя. Не перезаписывайте старую версию молча ломающим изменением. Публикуйте новую схему с журналом изменений, перечнем затронутых записей, сопоставлением старого и нового, тестом совместимости, датой прекращения поддержки и архивной связью.
Простыми словами
Представьте карту городских дорог. Исправить опечатку в названии улицы — не то же самое, что закрыть мост и открыть новую дорогу. Пользователям нового маршрута нужны дата, альтернатива и срок, до которого старая карта ещё пригодна.
Почему это важно
Тихое удаление поля или изменение правила может заставить старые приложения неверно прочитать данные и породить разные положения в разных языках. Одного номера версии недостаточно: должны быть известны последствия и маршрут перехода.
Не путать
- Исправление написания — редакторская правка, не меняющая существенный смысл.
- Обратно совместимое добавление даёт новое поле или вариант, не ломая старых потребителей.
- Ломающее изменение схемы может заставить старого потребителя работать неверно или неполно.
- Нормативное изменение меняет требование или запрет; это не только техническая правка схемы.
- Прекращение поддержки — жизненный цикл с объявленным окончанием и маршрутом перехода, а не мгновенное удаление поля.
Что делать
- Определите публичные поля, нормативные записи и файловые контракты в версионированной форме.
- Классифицируйте каждое изменение как редакторское, обратно совместимое, ломающее, нормативное или связанное с безопасностью.
- В журнале изменений укажите поле, причину, затронутые записи, дату и владельца решения.
- Свяжите человеческую, JSON-, schema-, API-, PDF- и языковые версии с одним заявлением о выпуске.
- Для ломающего изменения дайте сопоставление старых и новых полей, пример преобразования и средство или инструкцию миграции.
- Заранее объявите предупреждение, период поддержки, дату удаления и безопасный запасной путь.
- Проверьте обратную совместимость на старых примерах, новую схему и паритет — на новых, а выпуск сохраните неизменяемо.
Как проверить
- Явны ли класс изменения и его существенный эффект?
- Обозначает ли номер версии один и тот же выпуск на каждой поверхности?
- Не скрыто ли ломающее изменение под видом мелкого исправления?
- Полны ли журнал изменений, затронутые записи и маршрут миграции?
- Проверена ли совместимость со старыми потребителями и файлами?
- Есть ли у устаревающего поля дата, предупреждение и альтернатива?
- Доступна ли старая версия неизменяемо и связана ли она с новой?
Ограничение
Схема нумерации MAJOR.MINOR.PATCH полезно сигнализирует тип изменения, но не доказывает совместимость. Одна правка может по-разному влиять на книгу, нормативное положение, набор данных и API. Необходимость безопасности или права может сократить миграционный период, но причина и последствия всё равно должны быть записаны.
Запомните одной фразой
Новый выпуск — не только новый номер, но и объяснённое обещание об изменении.
Источники этой записи
- S07W3C, *JSON-LD 1.1*Стандарты
- S14DataCite, *Versioning*Инфраструктура идентификации
- S15DataCite, *Connecting Versions with Related Identifiers*Инфраструктура идентификации
- S35W3C, *PROV-O: The PROV Ontology*Стандарты
- S53JSON Schema, *Specification — Draft 2020-12*Открытая техническая спецификация
- S54*Semantic Versioning 2.0.0*Спецификация открытого управления версиями
- S58Zenodo, *About Records*Официальная документация хранилища данных