Open Manuscript Initiative Животният цикъл на спецификацията

Статус: Чернова
Версия: 0.1
Тип документ: Политика за управление
Език на нормативните документи: английски

1. Цел

Настоящата политика определя как се предлагат, разработват, преразглеждат, внедряват, стабилизират, обявяват за остарели и заменят спецификациите на Open Manuscript Initiative.

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

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

2. Общ преглед на жизнения цикъл

Exploratory
    ↓
Draft
    ↓
Review Candidate
    ↓
Implementation Candidate
    ↓
Stable
    ↓
Deprecated
    ↓
Superseded

Не е необходимо спецификацията да премине през всички етапи, ако бъде оттеглена преди публикуването ѝ. Документът МОЖЕ да се върне към по-ранен етап, ако бъдат открити съществени нерешени проблеми.

3. Нормативна терминология

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

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

4. Необходими метаданни за документите

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

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

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

5. Проучвателен

5.1 Цел

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

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

5.2 Критерии за допускане

Документът може да премине в това състояние, когато:

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

5.3 Очаквания

Един проучителен документ МОЖЕ:

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

Тя ТРЯБВА ясно да разграничи установените изисквания от отворените въпроси.

5.4 Критерии за завършване

За преминаване към „Draft“ е необходимо:

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

Едно проучвателно предложение МОЖЕ вместо това да бъде приключено като отхвърлено, отложено или извън обхвата.

6. Проект

6.1 Цел

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

Предварителната версия на съдържанието е нестабилна и МОЖЕ да претърпи промени, които да доведат до несъвместимост.

6.2 Критерии за допускане

Проектът ТРЯБВА да включва:

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

6.3 Очаквания

Проектът ТРЯБВА да включва:

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

Експерименталните реализации МОГАТ да заявяват, че поддържат проект на спецификацията, само ако посочат точната версия на спецификацията или конкретния коммит.

6.4 Критерии за завършване

За повишение в ранг „кандидат за преглед“ се изисква:

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

7. Проверка на кандидата

7.1 Цел

Кандидатът за преглед се счита за достатъчно изчерпателен, за да бъде подложен на целенасочен обществен и експертен преглед.

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

7.2 Критерии за допускане

Кандидатът за преглед ТРЯБВА:

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

7.3 Изисквания за преглед

Прегледът ТРЯБВА да включва гледни точки от повече от една заинтересована група, като например:

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

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

7.4 Критерии за завършване

За да бъдете одобрен за кандидат за внедряване, е необходимо:

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

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

8. Кандидат за внедряване

8.1 Цел

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

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

8.2 Критерии за допускане

Кандидатът за внедряване ТРЯБВА да предостави:

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

8.3 Доказателства за изпълнението

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

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

Доказателствата за внедряването ТРЯБВА да показват:

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

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

8.4 Критерии за излизане

За да бъдете повишени в ранг „Стабилен“, е необходимо:

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

При значителна корекция в проекта се налага връщане към етапа „Чернова“ или „Кандидат за преглед“. При по-незначителни корекции статутът „Кандидат за внедряване“ МОЖЕ да бъде запазен с нова предстабилна версия.

9. Стабилен

9.1 Значение

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

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

9.2 Изисквания

Една спецификация на „Stable“ ТРЯБВА да съдържа:

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

9.3 Контрол на промените

Промените в спецификацията на „Stable“ се класифицират като:

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

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

Съвместимите разширения обикновено изискват издаване на малка версия.

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

9.4 Поправки

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

В поправката ЗАДЪЛЖИТЕЛНО трябва да се посочи:

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

10. Не се препоръчва

10.1 Значение

„Отпаднало“ означава, че дадена спецификация остава достъпна и все още може да бъде внедрена, но при новите внедрявания СЛЕДВА да се дава предпочитание на нейния наследник или на алтернатива.

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

10.2 Изисквания за премахване на функции

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

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

Остарелите схеми, пространствата от имена и каноничните URL-адреси ТРЯБВА да останат достъпни с оглед дългосрочното съхранение.

11. Отменено

11.1 Значение

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

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

11.2 Изисквания

В документа ТРЯБВА да бъдат посочени:

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

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

12. Допълнителни крайни резултати

Не всяко предложение се превръща в „Стабилно“. В документите за управление работата МОЖЕ също да бъде класифицирана като:

Отхвърлено

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

Оттеглено

Авторът или редакторът е прекратил активната разработка преди приемането.

Отложено

Работата е потенциално ценна, но умишлено се отлага.

Обединени

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

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

13. Преходи между състояния

13.1 Заявка за промоция

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

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

13.2 Протокол за взетото решение

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

В документа ТРЯБВА да бъдат посочени:

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

13.3 Регресия

Една спецификация МОЖЕ да се върне към по-ранно състояние, когато:

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

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

14. Версии и статус на жизнения цикъл

Версията и състоянието на жизнения цикъл са свързани, но са различни понятия.

Примери:

• 0.2 Draft
• 0.8 Review Candidate
• 0.9 Implementation Candidate
• 1.0 Stable
• 1.1 Stable
• 1.0 Deprecated

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

15. Декларации за съответствие

Реализациите, които претендират за съответствие, ТРЯБВА да посочват:

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

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

Съответствието с версиите „Draft“, „Review Candidate“ или „Implementation Candidate“ ТРЯБВА да бъде описано като експериментално или предстабилно.

16. Зависимости

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

Една спецификация на Stable МОЖЕ да зависи от:

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

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

17. Политика за превод

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

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

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

Преводът НЕ ТРЯБВА да бъде обозначен като „Стабилен“, когато не съответства на актуалния стабилен източник на английски език.

18. Изисквания за архивиране

Версиите „Candidate за публикуване“, „Candidate за внедряване“, „Стабилна“, „Остаряла“ и „Заменена“ ТРЯБВА да останат постоянно достъпни.

Проектът ТРЯБВА да запази:

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

Каноничните URL адреси ТРЯБВА да останат непроменени или да пренасочват към архивна начална страница.

19. Корекции в спешни случаи

Сериозен недостатък, свързан със сигурността, поверителността, загубата на данни или оперативната съвместимост, МОЖЕ да наложи ускорено отстраняване.

При справяне с извънредни ситуации все пак ТРЯБВА да се осигури:

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

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

20. Задължения

Редактори на спецификации

Редакторите отговарят за:

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

Изпълнители

На изпълнителите се препоръчва:

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

Управление на проекта

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

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

21. Минимални изисквания според статуса

Изискване	Проучвателна фаза	Чернова	Кандидат за преглед	Кандидат за внедряване	Стабилна версия
Определен проблем	Задължително	Задължително	Задължително	Задължително	Задължително
Определен обхват	Препоръчително	Задължително	Задължително	Задължително	Задължително
Постоянен или запазен идентификатор	Незадължително	Задължително	Задължително	Задължително	Задължително
Нормативни изисквания	Незадължително	Частично	Пълно	Пълно	Пълно
Примери	Незадължително	Препоръчително	Задължително	Задължително	Задължително
Схема/формален модел, където е приложимо	Незадължително	Препоръчително	Задължително	Задължително	Задължително
Публично преразглеждане	Незадължително	Препоръчително	Задължително	Задължително	Завършено
Доказателства за внедряване	Не се изисква	По избор	Планирано	Задължително	Задължително
Тестове за съответствие	Не се изискват	По избор	Планирани	Изискват се, където е приложимо	Поддържат се
Политика за съвместимост	Не се изисква	Първоначално	Изисква се	Изисква се	Изисква се
Декларация за съответствие на продукцията	Забранено	Експериментално	Експериментално	Предстабилно	Разрешено

22. Осиновяване

Настоящата политика влиза в сила след одобрението ѝ в рамките на процеса на управление на „Open Manuscript Initiative“.

На съществуващите документи СЛЕДВА да бъде присвоен точен статус на жизнения цикъл в рамките на програмата за рефакторинг на документацията. Никой съществуващ документ не придобива статуса „Стабилен“ единствено поради факта, че е създаден преди въвеждането на настоящата политика.

23. Обобщение

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

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