Семантичната версии 2

Като се има предвид броя версия MAZHORNAYA.MINORNAYA.PATCH трябва да се увеличи:

1. Майор версия, когато се правят промени несъвместими API назад.
2. Малки версии, при добавяне на нови функции, без да се скъса обратна съвместимост.
3. PATCH версия, когато подкрепи поправки със съвместимостта.

Допълнителни наименования за изграждане предпускови и метаданни предлага като добавка към MAZHORNAYA.MINORNAYA.PATCH формат.

влизане

Процесът на разработване на управление на света, е концепцията за "зависимостта ада» (зависимостта ада). Колкото повече си система расте и колкото повече се интегрират библиотеки в проекта си, толкова по-вероятно да бъде в тази ситуация.

В система с множество зависимости нова версия може бързо да се превърне в кошмар. Ако спецификацията зависимост твърде трудно, вие сте в опасност от блокиране на освобождаването на нова версия (неспособност да се актуализира на пакета без да е необходимо да се освободи нова версия на всеки зависими библиотеки). Ако спецификацията на зависимост е прекалено хлабав, вие неизбежно ще изпревари Версия несъответствие (необосновано поемане на съвместимост с бъдещите версии).

Като решение на този проблем, аз предлагам един прост набор от правила и норми, които определят как номера на версията са възложени и се увеличават. За да може тази система да работи, трябва да се определи обществения API. Тя може да бъде описана в документацията или определено от кода. Основното нещо, което този API е ясно и точно. След като е определено публично API, ти го кажа за промените в специален увеличаването на номерата на версиите. Помислете за версията на X.Y.Z формат (масивно, слабо, кръпка). Корекции на грешки, не влияе на API, увеличаване на кръпка версия обратно съвместим промени добавка / API увеличават незначително версия и API обратно несъвместими промени увеличават основна версия.

Аз наричам тази система "Семантичната Versioning» (Semantic Versioning). По тази схема, номерата на версия и начина, по който те се променят, създаде чувство за съдържанието на изходния код и че е бил променен от една версия на друга.

Спецификация на семантичния версии (SemVer)

Софтуер, който използва семантичната Версиите, трябва да декларират публично API. Този API може да бъде обявена от кода или съществува строго в документацията. Без значение как се прави, то трябва да бъде точна и пълна.

Нормално номер на версията трябва да бъде в X.Y.Z формат, където X, Y и Z - отрицателни числа и не трябва да започва от нулата. X - основна версия, Y - малката версия, и Z - пластир версия. Всеки елемент трябва да се увеличава числено. Например: 1.9.0 -> 1.10.0 -> 1.11.0.

Майор версия нула (0.y.z) за първоначалното развитие. Всичко може да се промени по всяко време. Публична API не трябва да се счита за стабилен.

Версия 1.0.0 определя публично API. След това, номерата на версия освобождаване се увеличават в зависимост от начина, по който публично API.

Patch версия на Z (x.y.Z | х> 0) трябва да се увеличи само ако съдържа обратно съвместим корекции на грешки. Определяне на бъг-Fix означава вътрешни промени, които определят неправилното поведение.

Малолетните и непълнолетните версия (x.Y.z | х> 0) трябва да се увеличи, ако публично API въвежда нов обратна съвместимост функционалност. Тя трябва да се увеличи, ако функционалност публично API се маркира като остаряла (оттеглено). Тя може да се увеличи в случай на нови функции или значителното подобрение в частния код. Това може да включва промени характерни петна. Patch версия трябва да се нулира, когато малки версия се увеличава.

Майор версия X (X.y.z | X> 0) трябва да се увеличи, ако има такива изостанали несъвместими промени са представени в публично API. Това може да включва промени, показателни за нивото на по-малките версии и поправки. Когато най-големите увеличения версия, незначителни и кръпка версии трябва да бъдат нулирани.

версия Предварително освобождаване може да се посочи чрез добавяне на тире и серия от точкови разделени идентификатори, непосредствено след версия на пластира. Документи за самоличност трябва да съдържат само ASCII букви и цифри и тире [0-9a-Za-Z-]. Идентификатори трябва да се попълни. Цифрови идентификатори не трябва да започват от нулата. предварителните версии имат по-нисък приоритет от версията на съответния освобождаване. версия преди публикация показва, че този вариант не е стабилен и не може да отговаря на изискванията за оперативна съвместимост на определена съответната нормалната версия. Примери: 1.0.0-алфа, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

Приоритетът определя колко версии са свързани помежду си, когато нареди. Приоритетни версии трябва да се изчисляват, като се раздели броят на версия в големите, малките и кръпка predreliznogo идентификатори. В този ред (монтаж метаданни не е включена в изчислението). Приоритет се определя от първата разлика в сравнението на всеки един от тези показатели от ляво на дясно: големи, малки, и кръпка версия винаги е сравняван числено. Пример 1.0.0 <2.0.0 <2.1.0 <2.1.1. Когда мажорная, минорная и патч-версия равны, предрелизная версия имеет более низкий приоритет, чем нормальная версия. Пример: 1.0.0-alpha <1.0.0. Приоритет двух предрелизных версий с одинаковыми мажорной, минорной и патч-версией ДОЛЖНЫ быть определены сравнением каждого разделённого точкой идентификатора слева направо до тех пор, пока различие не будет найдено следующим образом: идентификаторы, состоящие только из цифр, сравниваются численно; буквенные идентификаторы или дефисы сравниваются лексически в ASCII-порядке. Численные идентификаторы всегда имеют низший приоритет, чем символьные. Больший набор предрелизных символов имеет больший приоритет, чем меньший набор, если сравниваемые идентификаторы равны. Пример: 1.0.0-alpha <1.0.0-alpha.1 <1.0.0-alpha.beta <1.0.0-beta <1.0.0-beta.2 <1.0.0-beta.11 <1.0.0-rc.1 <1.0.0.

Защо се използва семантичен версии?

Това не е нова или революционна идея. Вие сте вероятно вече използвате нещо подобно. Проблемът е, че "като" - не е достатъчно добър. Без подходяща формална спецификация, номерата на версиите са почти безполезни за управление на зависимостите. Ясно да определи и формулира идеята за създаване на версии, става по-лесно да се информират потребителите за намеренията на своя софтуер. Когато тези намерения са ясни, гъвкави (но не прекалено), може най-накрая да бъде създадена спецификацията на зависимости.

Един прост пример показва как семантично Versioning може да направи "зависимостта ада" нещо от миналото. Представлява библиотека, наречена «пожарна кола». Семантично, тя изисква версийте пакет, наречен «Стълба». Когато пожарна кола е създадена, стълба е версия 3.1.0. Тъй като пожарна кола използва функционална версия 3.1.0, можете спокойно да обяви зависимостта от Ladder версия 3.1.0, но по-малко от 4.0.0. Сега, когато е налична Ladder 3.1.1 и 3.2.0 версия, можете да го интегрират в системата ви и знам, че ще бъде съвместим с текущата функционалност.

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

Ако това ви звучи съблазнително, всичко, което трябва - трябва да започне да се използва семантично версии, обяви, че използвате, и следвайте правилата. Добавяне на връзка към сайта ви в README, потребителите ще знаят правилата и се възползват от предимствата.

Какво да правя с ревизираните данни в 0.y.z в началния етап на развитие?

Най-простото нещо - да започнем да развиваме с 0.1.0 и след това да се увеличи незначително версия за всяка следваща версия.

Как мога да разбера кога е време да се направи 1.0.0 за освобождаване?

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

Дали това пречи на бързото развитие и кратки повторения?

Майор версия 0 просто означава бързо развитие. Ако промените API всеки ден, трябва да бъде на 0.y.z версия или на отделен клон на работата по разработването на следващата голяма версия.

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

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

Документиране всички API - твърде много работа!

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

Какво да направя, ако случайно неиздавани назад несъвместими промени като малка версия?

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

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

Какво става, ако случайно се промени общественото API в несъответствие с промяната на номера на версията (т.е., кодът съдържа несъвместими промени обратно към освобождаването на пластир)?

По ваша преценка. Ако имате огромна аудитория, която ще бъде поставена преди API връща старото поведение факта, че е по-добре да пусне нова версия с увеличение на основната версия, въпреки факта, че поправката съдържа ниво на грешки кръпка. Не забравяйте, че в номерата на версиите Семантичната версии варират при стриктно спазване на изискванията. Ако тези промени са важни за потребителите си, да се използва номерът на версията за да ги информира.

Какво да правим с остарели функции?

Има ли версия SemVer ограничения за дължината на низ?

Не, но използват здравия разум. 255 символа на ред версия е вероятно Overkill. В допълнение, някои системи могат да наложат свои собствени ограничения за размера на низа.

Ако искате да оставите коментар, моля да отправи искане до GitHub.