Преминете към основното съдържание

Open Manuscript Initiative Политика за версиите

Статус на документа​

  • Тип документ: Политика за управление
  • Статус: Чернова
  • Версия: 0.1.0
  • Език на нормативите: английски
  • Приложимо за: спецификации, схеми, файлови формати, API, примери, реализации, преводи и публикувана документация на OMI

1. Цел​

Настоящата политика определя начина, по който „Open Manuscript Initiative“ (OMI) присвоява, тълкува, публикува и изтегля версии.

Идентификаторите на версиите дават представа за очакванията относно съвместимостта. Те не са просто етикети на версиите. Версията „OMI“ трябва да позволява на авторите, разработчиците, валидаторите, издателите, хранилищата и системите за съхранение да определят:

  • кои правила за спецификацията се прилагат;
  • дали се очаква два документа или две реализации да са съвместими помежду си;
  • дали дадено обновяване е обратно съвместимо;
  • дали е необходима миграция;
  • коя схема проверява валидността на документа;
  • кои корекции или допълнения са включени;
  • дали дадена версия продължава да се поддържа.

Настоящата политика допълва „Specification Lifecycle“. Статусът в жизнения цикъл описва степента на зрялост; номерата на версиите описват промените и съвместимостта. Дадена спецификация може да остане със статус „Чернова“, докато преминава през няколко версии преди версия 1.0.

2. Обхват​

Настоящата политика урежда управлението на версиите на:

  1. наборът от спецификации „OMI“;
  2. отделни документи от типа „OMI-SPEC“;
  3. каноничният модел на данни OMI и схемата JSON;
  4. OMI формати на ръкописи и контейнери;
  5. OMI APIдоговори за услуги и протоколи;
  6. нормативни речници и регистри;
  7. профили за съответствие;
  8. примерни модели и тестови приспособления;
  9. референтни реализации, включително Open Manuscript Studio;
  10. официални преводи;
  11. уебсайтът „OMI“ и комплектът от публикации с документация.

Не се изисква софтуерът на трети страни да използва същите номера на версиите на продукта, както спецификацията „OMI“. Софтуерът на трети страни обаче трябва да посочи кои версии и профили на „OMI“ поддържа.

3. Нормативни термини​

Ключовите думи ТРЯБВА, НЕ ТРЯБВА, ЗАДЪЛЖИТЕЛНО, СЛЕДВА, НЕ СЛЕДВА, ПРЕПОРЪЧВА СЕ, НЕ СЕ ПРЕПОРЪЧВА, ПРЕПОРЪЧИТЕЛНО, МОЖЕ и НЕЗАДЪЛЖИТЕЛНО трябва да се тълкуват като нива на нормативни изисквания.

4. Размери на версията​

OMI разграничава няколко свързани, но независими измерения на версиите.

4.1 Версия на набора от спецификации​

Версията „suite“ обозначава съгласувано публикуване на стандарта „OMI“, например:

OMI 0.2
OMI 1.0
OMI 1.1
OMI 2.0

Едно издание на пакет определя тествана комбинация от версии на спецификации, схеми, речници, профили и примери.

4.2 Версия на индивидуалната спецификация​

Всеки идентификатор на постоянна спецификация има своя собствена версия:

OMI-SPEC-005 Citation Model, version 0.3.0

Дадена спецификация може да бъде преработена, без това да води до незабавно пускане на нова версия на пакета. В регистъра на версиите на пакета се записва точната версия на всяка включена спецификация.

4.3 Версия на схемата​

Схемата, която може да се чете от машина, има ясно определена версия, независима от името на файла, комита в хранилището и датата на публикуване.

Пример:

{
  "$id": "https://openmanuscript.org/schemas/omi-manuscript-1.0.schema.json",
  "title": "Open Manuscript Manuscript Schema",
  "version": "1.0.0"
}

4.4 Версия на формата​

Всяка сериализирана ръкопис или пакет от типа „OMI“ ТРЯБВА да посочва версията на формата, необходима за неговото интерпретиране.

Пример:

{
  "omi": {
    "format": "manuscript",
    "version": "1.0.0"
  }
}

Точната структура на полетата ще бъде определена в спецификацията за формата на файла. Декларацията ТРЯБВА да остане машинно четима и НЕ ТРЯБВА да зависи единствено от разширението на името на файла.

4.5 Версия на реализацията​

Софтуерните продукти използват свои собствени версии, например:

Open Manuscript Studio 0.4.0

Версията на имплементацията НЕ ТРЯБВА да се тълкува като версия за съответствие с OMI. Имплементациите ТРЯБВА да декларират отделно поддържаните версии на OMI.

Пример:

Product version: 0.4.0
Supported OMI suite: 0.2
Supported manuscript format: 0.2.0–0.2.x

4.6 Версия на превода​

Официалният превод ТРЯБВА да посочва:

  • нормативният документ на английски език;
  • точната версия на изходния код;
  • преразглеждане на превода;
  • състоянието на синхронизацията.

Пример:

Source: OMI-SPEC-005 version 1.1.0
Translation revision: hu-1
Status: synchronized

5. Формат на номера на версията​

OMI използва семантични номера на версиите във формата:

MAJOR.MINOR.PATCH

Примери:

0.3.0
1.0.0
1.2.4
2.0.0

При имена на пакети, предназначени за крайни потребители, компонентът „patch“ може да бъде пропуснат, когато стойността му е нула:

OMI 1.0

Каноничната стойност, подходяща за машинно четене, остава 1.0.0.

6. Значение на компонентите на версията​

6.1 ОСНОВНИ​

Номерът на версията се променя, когато дадена версия въвежда несъвместими нормативни промени.

Сред основните промени са, наред с другото:

  • премахване на задължителна или поддържана досега структура от данни;
  • промяна на значението на съществуващо поле или обект;
  • превръщане на незадължителни данни в задължителни без подходяща стойност по подразбиране;
  • промяна на семантиката на идентификаторите;
  • промяна на правилата за обработка, така че съвместима по-стара реализация да дава съществено различни резултати;
  • замяна на модел за сериализация по начин, който не позволява безопасно четене от по-стари реализации;
  • въвеждане на несъвместимо поведение на API;
  • което прави невалидни преди това валидни документи, отговарящи на изискванията, без да е предвиден механизъм за съвместимост.

Всяка МАСОВА версия ТРЯБВА да включва указания за миграция.

6.2 НЕСЪВЪРШЕНОЛЕТНИ​

Номерът на MINOR се променя, когато се добави съвместима функционалност.

Незначителна промяна може да включва:

  • добавяне на незадължителни полета;
  • добавяне на нови типове обекти чрез дефинирана точка за разширение;
  • добавяне на нови опционални профили за съответствие;
  • добавяне на нови изброени стойности, когато потребителите вече са принудени да приемат неизвестни стойности;
  • добавяне на съвместими крайни точки от типа „API“;
  • разширяване на валидирането с предупреждения, които не правят вече валидното съдържание невалидно;
  • добавяне на съответствия към външни стандарти;
  • добавяне на информативни указания или примери, които изясняват желаното поведение.

При всяко МАЛКО обновяване ТРЯБВА да се запази възможността на съвместимите по-стари потребители да обработват основните данни, които са били поддържани и преди, дори ако те пренебрегнат нововъведената незадължителна информация.

6.3 ПАТЧ​

Номерът на PATCH се променя при съвместими корекции и уточнения.

Промяната в кръпката може да включва:

  • коригиране на редакционни грешки;
  • поправяне на неработещи връзки;
  • изясняване на двусмислен текст, без да се променя желаното поведение;
  • коригиране на примерите, за да съответстват на съществуващите нормативни правила;
  • коригиране на прекалено широко или прекалено тясно ограничение в схемата, когато предвиденото правило вече е било недвусмислено;
  • публикуване на поправки;
  • коригиране на преводи;
  • поправяне на ненормативни инструменти или документация.

Във версията на кръпка НЕ СЕ ДОПУСКА въвеждането на нова задължителна функционалност или съзнателно нарушаване на съвместимите реализации.

7. Версии преди 1.0​

Версиите под 1.0.0 означават, че съответната спецификация, схема или формат все още не са достигнали първата си стабилна версия, за която е поето задължение за съвместимост.

Примери:

0.1.0
0.2.0
0.2.3

По време на фазата „0.x“:

  • възможно е да възникнат несъвместими промени в версия от типа „MINOR“;
  • Издадените ПАТЧОВЕ ТРЯБВА да останат обратно съвместими в рамките на една и съща линия на МИНОРНИ версии;
  • всяка промяна, водеща до несъвместимост, ТРЯБВА да бъде документирана;
  • миграциите ТРЯБВА да се предоставят, когато това е възможно;
  • реализациите НЕ ТРЯБВА да претендират за дългосрочна съвместимост, основаваща се единствено на версия, предшестваща 1.0;
  • Публикуваните документи ТРЯБВА да запазват декларацията за оригиналната си версия, дори и след като вече съществува по-нова схема.

Фазата „0.x“ не означава, че промените могат да се извършват безконтролно. Всяко издание продължава да подлежи на изискванията за преглед, списък с промените и архивиране.

8. Ангажимент за стабилност на ниво 1,0​

Версия 1.0.0 установява първата стабилна базова линия за съвместимост с „OMI“.

Преди даден компонент да достигне етапа „1.0.0“, той ТРЯБВА да отговаря на приложимите изисквания на политиката за жизнения цикъл на спецификациите, включително:

  • ясно очертан обхват;
  • уеднаквена терминология;
  • изпълнение на нормативните изисквания;
  • стабилни идентификатори;
  • схеми, подходящи за машинно четене, където това е уместно;
  • критерии за съответствие;
  • доказателства за прилагане;
  • тестване на оперативната съвместимост;
  • съображения, свързани със сигурността и опазването;
  • правила за миграция от последната версия преди 1.0;
  • публично обсъждане.

След „1.0.0“ промените, които не са съвместими с предишните версии, изискват нова ОСНОВНА версия, освен ако изричен механизъм за съвместимост вече не е бил част от стабилната спецификация.

9. Определения за съвместимост​

9.1 Назад съвместимост​

Една по-нова реализация е обратно съвместима, когато може правилно да обработва съдържание, валидно съгласно поддържаната по-стара версия, без да се налагат промени, освен в случаите, когато по-старото съдържание зависи от оттеглена небезопасна функция, документирана в политиката.

9.2 Съвместимост с бъдещи версии​

Една по-стара реализация е съвместима с по-нови версии, когато може безопасно да обработва по-ново съдържание, обикновено като игнорира неизвестни опционални разширения, като същевременно ги запазва, когато това е необходимо.

OMI цели да осигури ограничена напредна съвместимост. Реализациите не са длъжни да разбират неизвестна семантика, но ТРЯБВА да се провалят безопасно и НЕ ТРЯБВА да преинтерпретират неизвестни данни без предупреждение.

9.3 Съвместимост при двупосочно движение​

Съвместимостта в двете посоки означава, че съдържанието може да се зарежда и запазва без загуба на информацията, която реализацията е длъжна да съхрани.

Потребител, който не разбира дадено разширение, ВЪЗМОЖНО е все пак да отговаря на изискванията, ако запази това разширение без промени в съответствие с правилата за разширенията.

9.4 Съвместимост на поведението​

Поведенческата съвместимост засяга резултатите от обработката, а не само валидността на схемата. Две версии са поведенчески съвместими, когато задълженията за нормативна интерпретация, валидиране, закрепване, разрешаване на цитати и визуализация остават еднакви за съществуващото съдържание.

10. Правила за съвместимост на моделите на данни​

10.1 Допълнителни елементи по избор​

Новите опционални свойства обикновено представляват МАЛКИ промени, когато:

  • липсата им има конкретно значение;
  • на по-възрастните потребители се разрешава да ги игнорират или да ги запазят;
  • те не променят интерпретацията на съществуващите полета.

10.2 Необходими допълнения​

Добавянето на задължително свойство обикновено представлява СЪЩЕСТВЕНА промяна, освен ако:

  • определена е детерминистична стойност по подразбиране;
  • съществуващите валидни документи запазват валидността си или могат да бъдат актуализирани без загуба на смисъла;
  • механизмът за съвместимост вече имаше нормативен характер.

10.3 Изнасяне на имущество​

Премахването на свойство е СЪЩЕСТВЕНА промяна. Преди премахването ТРЯБВА да се извърши отмяна на поддръжката.

10.4 Преименуване​

Промяната на името на обект представлява СЪЩЕСТВЕНА промяна, освен ако старото име продължава да се приема чрез документиран псевдоним или през преходен период.

10.5 Промени в типа​

Промяната на типа или кардиналността на даден атрибут обикновено представлява СЪЩЕСТВЕНА промяна.

10.6 Изброявания​

Добавянето на стойности към изброяването се счита за МИНОРНО само когато потребителите трябва да приемат неизвестни стойности. В противен случай то се счита за МАЖОРНО.

Премахването или предефинирането на стойност от изброяване е СЪЩЕСТВЕНО.

10.7 Неизпълнение на задълженията​

Промяната на стойност по подразбиране, която засяга интерпретацията или изхода, се класифицира като MAJOR. Корекцията на документирана стойност по подразбиране, за да съответства на вече нормативното поведение, може да бъде класифицирана като PATCH, при условие че доказателствата за оперативна съвместимост потвърждават желаното поведение.

11. Обработка на неизвестни данни и разширения​

За да се подпомогне съвместимото развитие:

  • спецификациите ТРЯБВА да определят изрични точки за разширение;
  • реализациите ТРЯБВА да правят разграничение между неизвестни данни и невалидни данни;
  • неизвестните разширения НЕ ТРЯБВА да се тълкуват като известна основна семантика;
  • процесорите ТРЯБВА да запазват данните с неизвестни разширения по време на обмена, когато форматът изисква това;
  • валидаторите ТРЯБВА да идентифицират пространството от имена или профила, отговорен за дадено разширение;
  • разширението НЕ ТРЯБВА да променя основната семантика без нов съвместим профил или промяна на основната версия.

12. Версии на схемата​

12.1 Непроменяеми публикувани схеми​

Публикуваната схема, идентифицирана чрез каноничен URL адрес с версия, ТРЯБВА да бъде неизменна.

Например, съдържанието, достъпно на адрес:

https://openmanuscript.org/schemas/omi-manuscript-1.0.schema.json

НЕ ТРЯБВА да се заменят без предупреждение с правила, които водят до различно поведение.

Поправките изискват едно от следните:

  • нов URL на схемата на ниво пач; или
  • механизъм за поправки с ясно обозначени версии, който запазва оригиналния артефакт.

12.2 Канонични и удобни URL адреси​

OMI МОЖЕ да публикува URL адрес без версия, например:

https://openmanuscript.org/schemas/omi-manuscript.schema.json

Този URL адрес може да сочи към най-новата препоръчана стабилна схема и НЕ ТРЯБВА да се използва като единствен идентификатор в архивни документи.

Нормативните и архивираните документи ТРЯБВА да се позовават на неизменна схема с версии.

12.3 Идентификатори на схеми​

Всяка схема ТРЯБВА да включва:

  • каноничен $id;
  • явно изразена версия;
  • съответните препратки към спецификациите и наборите от тестове на „OMI“;
  • статус на публикуване;
  • бележки за съвместимост, където е приложимо.

12.4 Диалект на схемата​

Промяната на диалекта на схемата „JSON“ е решение, което засяга съвместимостта. Промяната на диалекта МОЖЕ да бъде МИНОРНА, ако наборът от допустими инстанции и семантиката на валидирането останат еквивалентни. В противен случай тя е МАЙОРНА.

13. Версии на файловите формати​

13.1 Самоидентификация​

Всеки файл или контейнер от типа „OMI“ ТРЯБВА вътрешно да посочва своя формат и версия.

Разширенията на имената на файловете и MIME-типовете са полезни метаданни за маршрутизиране, но не са достатъчни като единствен индикатор за версията.

13.2 Поведение на читателите​

Читателят ТРЯБВА:

  • да приема версии, които изрично поддържа;
  • безопасно да отхвърляте или поставяте в карантина неподдържани основни версии;
  • ясно посочете версията, която не се поддържа;
  • да се избягва унищожително преобразуване без съгласието на потребителя или разрешение съгласно политиката;
  • да се запази оригиналният артефакт при опит за миграция.

Четецът МОЖЕ да приеме по-нова НЕЗНАЧИТЕЛНА версия, когато правилата за съвместимост позволяват неизвестни опционални полета и разширения.

13.3 Поведение на писателя​

Всеки автор ТРЯБВА да посочи точната версия, която публикува.

Когато се изисква съвместимост с по-стари системи, писателят ТРЯБВА да генерира най-старата съвместима версия, която точно отразява съдържанието.

Авторът НЕ ТРЯБВА да маркира съдържанието като принадлежащо към по-стара версия, когато в него се използват функции, които не са допустими в тази версия.

13.4 Миграция​

Миграцията между версиите на форматите ТРЯБВА да бъде ясна и възпроизводима.

Един инструмент за миграция ТРЯБВА да генерира:

  • версия на изходния код;
  • целева версия;
  • инструмент за миграция и версия;
  • времева отметка;
  • предупреждения;
  • загуби или приблизителни стойности;
  • нерешени разширения;
  • резултат от валидирането;
  • връзка с произхода на оригиналния артефакт.

14. Управление на версиите вAPI​

OMI APIДоговорите за версиите на s MUST трябва да се сключват независимо от версиите на сървърния продукт.

14.1 Промени, нарушаващи съвместимостта с „API“​

Сред промените, изискващи адаптация, са:

  • премахване на крайни точки;
  • промяна на задължителните полета в заявката;
  • промяна на значението на отговора;
  • промяна на семантиката на удостоверяването;
  • промяна на договорите за кодове за състояние;
  • промяна на пагинацията, подреждането или поведението при едновременна работа по начин, който не е съвместим.

Промените, които водят до несъвместимост, изискват нова MAJOR версия на API.

14.2 Избор на версия на „API“​

Спецификацията на протокола „API“ ТРЯБВА да дефинира ясен механизъм за договаряне на версията, като например:

  • тип медия с версии;
  • път с версия;
  • изрично заглавие на протокола;
  • договорен профил на способностите.

Механизмът ТРЯБВА да бъде документирана последователно и НЕ ТРЯБВА да зависи от недокументирани сървърни хеуристики.

14.3 Период на премахване​

Стабилните функции от типа „API“ ТРЯБВА да бъдат обявени за остарели, преди да бъдат премахнати. Уведомлението за остаряването ТРЯБВА да включва:

  • засегнатата функция;
  • замяната;
  • най-ранната версия за премахване;
  • насоки за миграцията;
  • очакван период на поддръжка.

15. Версии на речника и регистъра​

Контролираните речници, списъците с роли, типовете обекти, схемите за идентификатори и регистрите на профили изискват ясно определени правила за развитие.

Регистрационният запис ТРЯБВА да има стабилен идентификатор. Етикетите за показване могат да се променят, без това да променя идентичността.

Добавянето на запис в регистъра обикновено е от категория „MINOR“. Премахването или предефинирането на съществуващ идентификатор е от категория „MAJOR“, освен ако записът не е бил изрично обозначен като експериментален или с локален обхват.

Остарелите записи ТРЯБВА да продължат да могат да се разрешават и ТРЯБВА да посочват заместителя си, когато такъв съществува.

16. Управление на версиите на профилите за съответствие​

Профилът за съответствие определя ограничено или разширено използване на OMI за даден работен процес, дисциплина, издател, хранилище или цел за обмен.

Всеки профил ТРЯБВА да съдържа следната информация:

  • идентификатор на профила;
  • версия на профила;
  • необходими версии на пакета „OMI“ и на спецификациите;
  • допълнителни ограничения;
  • разширени речници;
  • политика за съвместимост;
  • ресурси за валидиране.

Един профил НЕ ТРЯБВА да претендира за съвместимост с версия на OMI, чиито основни изисквания той нарушава.

17. Издания на набори от спецификации​

При всяко пускане на пакет от типа „OMI“ ЗАДЪЛЖИТЕЛНО трябва да се публикува манифест на версията.

В манифеста е отбелязано:

  • версия „Suite“;
  • дата на излизане;
  • статус на жизнения цикъл;
  • включително версиите OMI-SPEC;
  • версии на схеми и хешове;
  • версии на речника и регистъра;
  • профили за съответствие;
  • примери и версии на набора от тестове;
  • известни ограничения;
  • поддържани пътища за миграция;
  • заменени версии на пакета.

Версията на пакета НЕ ТРЯБВА да предполага, че всяка отделна спецификация има същия номер на версията.

18. Съгласуване на версиите​

Компонентите МОГАТ да използват независими семантични версии. Не се препоръчва изкуствено налагане на един и същ номер на всеки компонент от типа „OMI“, тъй като това замъглява действителния обхват на промените.

Манифестът на пакета осигурява съгласуваност.

Пример:

suite: 1.1.0
specifications:
  OMI-SPEC-001: 1.0.1
  OMI-SPEC-002: 1.1.0
  OMI-SPEC-005: 1.0.0
schemas:
  manuscript: 1.1.0
  annotation: 1.0.2

19. Декларации за подкрепа на изпълнението​

Всяка реализация, която претендира, че поддържа „OMI“, ТРЯБВА да публикува декларация за поддръжка, която е машинно четима или ясно структурирана.

Декларацията ТРЯБВА да включва:

  • име и версия на реализацията;
  • поддържани версии на пакета;
  • поддържани версии на форматите;
  • поддържани профили;
  • възможност за четене;
  • възможност за запис;
  • възможност за валидиране;
  • запазване на неизвестните разширения;
  • известни отклонения;
  • резултати от набора от тестове.

Следните претенции са различни:

  • чете „OMI“ 1.0;
  • записва „OMI 1.0“;
  • проверява OMI 1.0;
  • отговаря на стандарта „OMI“ версия 1.0, профил „Core“;
  • запазва неподдържаните разширения на OMI 1.x.

Общо формулирано твърдение като „съвместимо сOMI“ не е достатъчно за официално заявление за съответствие.

20. Версии на референтната реализация​

Open Manuscript Studio а другите софтуерни продукти, поддържани от OMI, следват собствените си семантични версии.

Дадена версия на софтуера МОЖЕ да поддържа няколко версии на OMI. В бележките към версията ТРЯБВА изрично да се посочи съвместимостта.

Промяната в потребителския интерфейс на Studio не налага промяна на версията на спецификацията „OMI“, освен ако тя не променя стандартизираните данни, обмена на данни или нормативното поведение.

От друга страна, новата версия на спецификацията „OMI“ не изисква всяка реализация да я приложи незабавно.

21. Управление на версиите на преводите​

21.1 Нормативен източник​

Освен ако изрично не е посочено друго, английският език е нормативният език на спецификациите на OMI.

21.2 Статус на синхронизацията​

Всеки официален превод ТРЯБВА да съдържа една от следните състояния:

  • Синхронизирано: отразява изцяло идентифицираната версия на източника;
  • Очаква се актуализация: източникът е променен и преводът се преработва;
  • Архивирано: преводът се отнася за по-стара поддържана версия на изходния код;
  • Оттеглено: преводът е ненадежден или вече не се актуализира.

21.3 Поправки, засягащи единствено превода​

Корекция, която променя само ревизията на превода, не променя версията на нормативната спецификация.

Корекцията на превода НЕ ТРЯБВА да променя без предупреждение препратката към изходната версия.

21.4 Конфликти​

В случаите, когато информативният превод противоречи на нормативния текст на английски език, предимство има текстът на английски език. Преводът ТРЯБВА да бъде коригиран незабавно, като корекцията се документира.

22. Управление на версиите на документацията на сайта​

Уебсайтът може да публикува актуални, разработвани и архивирани набори от документация.

Документацията за стабилните версии ТРЯБВА да остава достъпна на трайни URL адреси с версии.

Пример:

/docs/1.0/
/docs/1.1/
/docs/latest/
/docs/development/

latest е псевдоним за удобство и НЕ ТРЯБВА да се използва като единствена библиографска справка.

Документацията за стабилна версия НЕ ТРЯБВА да се променя със задна дата по начин, който променя нормативното ѝ значение. Поправките се публикуват чрез ерата или чрез версия с поправки.

23. Примери и тестови приспособления​

Примерите и тестовите набори за съответствие ТРЯБВА да посочват версията на „OMI“, към която са насочени.

Тестовата конфигурация, която променя очакваното нормативно поведение, изисква съответна промяна в спецификацията или версията на набора от тестове.

Примерите НЕ ТРЯБВА да се разглеждат като нормативни, когато са в противоречие с нормативен текст или схема. Такива противоречия са грешки, които изискват поправка.

24. Кандидатни версии и предварителни версии​

Идентификаторите за предварително издаване МОГАТ да се използват:

1.0.0-alpha.1
1.0.0-beta.2
1.0.0-rc.1

Те означават:

  • алфа: непълна, експериментална реализация или интеграция на спецификацията;
  • бета: версия с пълен набор от функции, но с нерешени проблеми, свързани с прегледа или оперативната съвместимост;
  • rc: кандидат за пускане, който се очаква да стане окончателната версия, освен ако не бъдат открити сериозни дефекти.

Предварителните версии НЕ ТРЯБВА да се представят като стабилни версии.

Предварителната версия МОЖЕ да съдържа промени преди окончателното публикуване. Промените между кандидат-версиите ТРЯБВА да се ограничават до отстраняване на дефекти и корекции на съвместимостта, които пречат на пускането на версията.

25. Създаване на метаданни​

Сборката на метаданни МОЖЕ да идентифицира конкретна сборка на реализацията, без да променя съвместимостта:

1.0.0+build.42
1.0.0+20260806.sha.abc1234

Метаданните за изграждане НЕ ТРЯБВА да променят нормативното тълкуване.

26. Прекратяване на поддръжката​

Обявяването за остаряла означава, че дадена функция или версия все още се признава, но не трябва да се използва за нова работа.

Уведомлението за преустановяване на поддръжката ТРЯБВА да съдържа следната информация:

  • отпадналият елемент;
  • версията, в която е била обявена за остаряла;
  • причината;
  • препоръчаната замяна;
  • известни съображения, свързани с миграцията;
  • най-ранната версия, в която може да се извърши премахване.

Самото премахване на поддръжката не води до това съвместими процесори да престанат да четат съществуващото съдържание.

27. Премахване​

Дадена стабилна функционалност се премахва само в рамките на ОСНОВНА версия, освен в случаите, когато е необходимо незабавното ѝ премахване с цел преодоляване на сериозен риск, свързан със сигурността, законодателството или целостта.

Спешното преместване изисква:

  • публично уведомление;
  • документирана обосновка;
  • анализ на въздействието;
  • насоки за съхранение;
  • алтернатива, когато това е възможно;
  • изричен запис за изключение.

28. Отмяна​

Отменената версия остава част от историческия архив.

На страницата с публикацията ТРЯБВА да са посочени:

  • заместващата версия;
  • дали е необходима миграция;
  • дали старата версия продължава да се поддържа;
  • датата, на която приключва поддръжката, ако е определена.

Артефактите с версии НЕ ТРЯБВА да се изтриват само защото са заменени.

29. Политика за поддръжка​

Преди версия 1.0 на „OMI“ поддръжката се осигурява в рамките на възможностите и се документира за всяка версия.

След версия 1.0 на OMI проектът ТРЯБВА да поддържа:

  • настоящата стабилна основна линия;
  • поне един документиран път на миграция от непосредствено предшестващата стабилна ОСНОВНА линия;
  • предупреждения относно сигурността и целостта за поддържаните версии, които са засегнати в значителна степен;
  • архивирани схеми и документация за всички стабилни версии.

В отделен график за поддръжка МОЖЕ да бъдат определени точни периоди за поддръжка.

30. Списък с промените​

Всяка публикувана версия ТРЯБВА да съдържа списък с промените.

В списъка с промените ЗАДЪЛЖИТЕЛНО трябва да се прави разграничение между:

  • промени, изискващи пренастройка;
  • съвместими допълнения;
  • поправки;
  • премахнати функции;
  • премествания;
  • промени в сигурността;
  • изисквания за миграция;
  • промени в схемата;
  • промени, свързани единствено с редакцията.

Всяка записка в дневника на промените ТРЯБВА да съдържа препратка към съответния проблем, предложение, заявка за промяна или запис за решение.

31. Документи, свързани с миграцията​

Всяка версия, съдържаща промени, нарушаващи съвместимостта, ТРЯБВА да включва документация за миграция.

Насоките за миграция ТРЯБВА да включват:

  • засегнати структури и поведение;
  • примери „преди и след“;
  • автоматизирани правила за трансформация;
  • ограничения;
  • очаквана загуба на информация;
  • етапи на валидиране;
  • стратегия за връщане към предишно състояние;
  • обработка на удължителите;
  • изисквания относно произхода.

32. Договаряне на версията​

Когато системите обменят динамично съдържание от типа „OMI“, те ТРЯБВА да договарят възможностите, вместо да приемат, че поддръжката е гарантирана въз основа на наименованията на продуктите.

Преговорите могат да включват:

  • поддържани версии на пакета;
  • поддържани диапазони от формати;
  • профили;
  • разширения;
  • типове медии;
  • нива на валидиране;
  • асиметрия при четене/запис.

Системата ТРЯБВА да се изключи безопасно, когато не може да бъде постигнато съгласие за съвместима версия.

33. Диапазони на версиите​

Реализациите МОГАТ да декларират диапазони на версиите.

Примери:

>=1.0.0 <2.0.0
1.1.x
1.0.0–1.2.3

Твърдението за обхват означава, че реализацията е проектирана и тествана за този обхват. То НЕ ТРЯБВА да се извежда единствено от приемането на схемата.

При архивните метаданни точните версии се предпочитат пред диапазоните.

34. Възпроизводимост и цялостност​

Публикуваните артефакти от версиите ТРЯБВА да включват криптографски хешове.

Стабилната версия ТРЯБВА да може да бъде възпроизведена въз основа на маркирания изходен код и документираните инструкции за компилиране.

Етикетите, използвани за стабилни версии, ТРЯБВА да бъдат неизменни.

Ако даден артефакт трябва да бъде заменен поради грешка в публикацията или опаковката, заместващият артефакт ТРЯБВА да получи различна ревизия или версия на артефакта, а първоначалният инцидент ТРЯБВА да бъде документиран.

35. Етикети и клонове в Git​

Препоръчителните етикети включват:

omi-suite-v1.0.0
omi-spec-005-v1.1.0
schema-manuscript-v1.0.2

Разработващите клонове и заявките за събиране не представляват версии на софтуера.

Клонът по подразбиране отразява текущата разработка и МОЖЕ да се различава от най-новата стабилна версия.

36. Дати и версии​

Датите на публикуване предоставят исторически контекст, но не заместват семантичните версии.

Идентификаторите, базирани на дата, МОГАТ да бъдат включени в метаданните и моменталните снимки, но нормативната съвместимост ТРЯБВА да бъде посочена чрез семантичната версия.

37. Процедура за вземане на решения​

Когато не е ясно с колко трябва да се увеличи версията, редакторите трябва да преценят:

  1. Промяната прави ли невалидно съдържанието, което преди това е било валидно?
  2. Променя ли това съществуващото нормативно значение?
  3. Могат ли по-старите съвместими реализации да обработват новото съдържание безопасно?
  4. Необходима ли е миграция?
  5. Въвежда ли това нова задължителна функционалност?
  6. Това променя ли резултатите от проверката за съответствие?
  7. Променя ли това външно наблюдаемото поведение на API?
  8. Промяната е ли само редакционна или корективна?

Ако една разумна и съответстваща реализация би могла да наруши или тихо да интерпретира погрешно съдържанието, промяната се счита за нарушаваща съвместимостта и изисква увеличение с ниво MAJOR, или увеличение с ниво MINOR по време на фазата преди версия 1.0, придружено от изрична документация за промяната, нарушаваща съвместимостта.

38. Примери​

38.1 Добавяне на незадължителен езиков таг за абстрактни езици​

Промяна: към абстрактния обект се добавят опционални метаданни от типа „language“.

Резултат след версия 1.0: НЕзначително, при условие че по-старите потребители могат да го игнорират или запазят.

38.2 Въвеждане на задължително използване на „ORCID“ за всеки автор​

Промяна: досегашният незадължителен параметър „ORCID“ вече е задължителен.

Резултат: СЕРИОЗЕН, тъй като съществуващите документи и работни процеси губят валидността си.

38.3 Поправяне на грешно изписана променлива в пример​

Промяна: в примера беше използвано „contributer“, докато в спецификацията вече се изискваше „contributor“.

Резултат: PATCH.

38.4 Преименуване на references на bibliography​

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

Резултат: МАЙОР.

Ако и двете свойства останат приети по време на документиран преход, въвеждането може да бъде от категория „MINOR“, докато окончателното премахване остава от категория „MAJOR“.

38.5 Добавяне на нова връзка между цитати​

Промяна: „qualifies“ се добавя към отворен регистър, чиито потребители трябва да приемат неизвестни стойности.

Резултат: НЕЗНАЧИТЕЛНО.

Ако изброяването е било затворено и неизвестните стойности са били невалидни, промяната може да изисква MAJOR.

38.6 Изясняване на реда на разрешаване на анкерните точки​

Промяна: текстът е прецизиран, за да съответства на единственото поведение, което се допуска от съществуващия алгоритъм и тестовете.

Резултат: PATCH.

Ако дадена реализация допуска две разумни, но противоречащи си тълкувания, изборът на едно от тях може да доведе до несъвместимост и да изисква версия MAJOR.

39. Рекорд за най-малко освободени лица​

Всеки запис, публикуван на OMI, ТРЯБВА да съдържа:

  • име на компонент или пакет;
  • версия;
  • статус на жизнения цикъл;
  • дата на излизане;
  • каноничен URL;
  • източник или комит;
  • списък с промените;
  • декларация за съвместимост;
  • изявление относно миграцията;
  • хешове на артефактите, където е приложимо;
  • информация за замяна;
  • известни проблеми.

40. Промени в политиката​

Самата тази политика за версиите също има различни версии.

Промяна, която променя смисъла на съществуващите ангажименти за публични версии, изисква внимателен преглед и НЕ ТРЯБВА да отслабва със задна дата вече поетите гаранции за стабилните версии.

Разясненията на политиката могат да представляват промени на ниво „пач“. Новите съвместими процедури за управление могат да представляват незначителни промени. Фундаменталните промени в ангажиментите за съвместимост изискват основна версия на политиката.

41. Обобщение​

OMI използва семантични версии, за да посочи съвместимостта между спецификации, схеми, формати, API, реализации, профили и преводи.

Ръководните принципи са:

  • версиите са ясно посочени и достъпни за машинно четене;
  • публикуваните версии на артефактите са неизменни;
  • значителните промени са ясно посочени и придружени от указания за миграция;
  • схемите и документите определят точните правила, които се използват;
  • версиите на продуктите се различават от съответствието със спецификациите;
  • стабилните версии остават архивирани и могат да бъдат цитирани;
  • твърденията за съвместимост трябва да бъдат точни и подлежащи на проверка;
  • преводите посочват оригиналната версия, на която се основават;
  • Манифестът на пакета съгласува компонентите с независими версии.

Тези правила позволяват на OMI да се развива, като същевременно се запазват научните документи, доверието в прилагането и дългосрочната оперативна съвместимост.