Semantica versionare 2

Având în vedere numărul versiunii MAZHORNAYA.MINORNAYA.PATCH ar trebui să fie crescută:

1. versiune majoră atunci când modificările sunt făcute API incompatibile înapoi.
2. versiuni minore, atunci când adăugați caracteristici noi fără a rupe compatibilitatea cu versiunile anterioare.
3. Versiunea PATCH, atunci când înapoi stabilește compatibilitatea.

desemnări suplimentare pentru a construi pre-lansare și metadate disponibile ca un supliment în format MAZHORNAYA.MINORNAYA.PATCH.

intrare

Procesul de dezvoltare de management din lume este conceptul de „dependență iad» (iad dependență). Cu cât este mai sistemul dvs. crește și mai mult va integra bibliotecile în proiectul dumneavoastră, cu atât mai probabil să fie în această situație.

Într-un sistem cu mai multe dependențe noi de eliberare se poate transforma rapid într-un coșmar. În cazul în care caietul de sarcini în funcție prea tare, vă aflați în pericol de a bloca lansarea unei noi versiuni (incapacitatea de a actualiza pachetul fără a fi nevoie de a lansa o nouă versiune a fiecărei biblioteci dependente). În cazul în care caietul de sarcini de dependență este prea slab, vă va depăși în mod inevitabil, versiunea incoerență (presupunerea nejustificată de compatibilitate cu versiunile viitoare).

Ca o soluție la această problemă, propun un simplu set de reguli și reglementări care definesc modul în care numerele de versiune sunt atribuite și sunt în creștere. Pentru ca acest sistem să funcționeze, trebuie să definiți API publice. Acesta poate fi descrisă în documentația sau definită de codul. Principalul lucru pe care acest API este clar și precis. Odată definit API publică, să-i spui despre schimbările în creșterea specială în numere de versiune. Luați în considerare versiunea X.Y.Z format (majore, minore, patch-uri). remedieri de erori, care nu afectează API, crește patchl înapoi modificări add / API-uri compatibile crește versiunea minoră și API spate modificări incompatibile crește versiunea majore.

Eu numesc acest sistem „semantic Versionare» (semantic Versionare). În cadrul acestui sistem, numerele de versiune și modul în care acestea schimba, pentru a transmite un sentiment de conținutul codului sursă și care a fost modificat de la o versiune la alta.

Specificarea semantic Versionare (SemVer)

Software-ul care folosește semantic Versionare, ar trebui să declare un API public. Acest API poate fi declarat de codul sau există strict în documentația. Nu contează cum se face, trebuie să fie corecte și complete.

Numărul versiunii normală ar trebui să fie în X.Y.Z format, în cazul în care X, Y și Z - numere întregi negative, și nu trebuie să înceapă de la zero. X - versiune majoră, Y - versiunea minoră, și Z - versiune de patch-uri. Fiecare element trebuie să crească numeric. De exemplu: 1.9.0 -> 1.10.0 -> 1.11.0.

versiune majoră zero (0.y.z) pentru dezvoltarea inițială. Totul se poate schimba în orice moment. API-ul public nu ar trebui să fie considerată ca fiind stabilă.

Versiunea 1.0.0 definește un API public. După aceea, numerele de versiune cu eliberare sunt crescute în funcție de modul în care API-ul public.

Versiunea Patch Z (x.y.Z | x> 0) trebuie crescută numai în cazul în care conține bug fixat înapoi compatibile. Definiția unui bug-fix înseamnă schimbări interne care fixează comportamentul incorect.

Versiunea minoră (x.Y.z | x> 0) ar trebui să fie crescută, în cazul în care un API publică introduce o nouă funcționalitate înapoi compatibile. Ar trebui să fie crescută în cazul în care o funcționalitate API-ul public este marcat ca fiind învechit (învechită). Acesta poate fi crescută în cazul noilor caracteristici sau îmbunătățirea semnificativă a codului privat. Aceasta poate include modificări patch-uri caracteristice. Versiunea Patch trebuie resetat atunci când versiunea minore crește.

Versiunea principală X (X.y.z | X> 0) ar trebui să fie crescută, în cazul în care orice modificări incompatibile în sens invers sunt prezentate într-un API public. Aceasta poate include modificări care indică nivelul versiunilor minore și patch-uri. Când majore crește versiunea, versiunile minore și patch-uri trebuie resetat.

versiune pre-release poate fi indicată prin adăugarea unei cratimă și o serie de identificatori separați-dot, imediat după versiunea patch. ID-urile trebuie să conțină doar caractere alfanumerice ASCII și cratima [0-9A-Za-Z-]. Identificatorii nu trebuie să fie gol. Identificatorii numerice nu trebuie să înceapă de la zero. Versiunile prelansate au o prioritate mai mică decât versiunea de lansare corespunzătoare. versiune pre-release indică faptul că această versiune nu este stabilă și nu poate îndeplini cerințele de interoperabilitate ale versiunii normale corespunzătoare desemnate. Exemple: 1.0.0-alfa, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

Prioritatea determină modul în care versiuni sunt legate între ele, atunci când a ordonat. Versiunile prioritare ar trebui să fie calculată prin împărțirea numerelor în versiunea majore, minore, și patch-uri identificatorii predreliznogo. În această ordine (metadate de asamblare nu este inclus în calcul). Prioritatea este determinată de prima diferență în compararea fiecăruia dintre acești identificatori de la stânga la dreapta: majore, minore și versiunea de patch-uri este întotdeauna comparat numeric. Exemplul 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.

De ce să folosiți versionare semantic?

Aceasta nu este o idee nouă sau revoluționară. Tu probabil deja folosind ceva de genul asta. Problema este că „ca“ - nu suficient de bun. Fără specificații formale corespunzătoare, numere de versiune sunt practic inutile pentru gestionarea dependenței. În mod clar să definească și să formuleze ideea de versionare, devine mai ușor de a informa utilizatorii cu privire la intențiile software-ul. Atunci când aceste intenții sunt clare, flexibile (dar nu prea), pot fi create în cele din urmă specificația dependențelor.

Un exemplu simplu arată cum Versionare semantic poate face „dependența de iad“ de domeniul trecutului. Reprezentați bibliotecă numită «Firetruck». Semantically, este nevoie de un pachet de versionat numit «Ladder». Când a fost creat Firetruck, Ladder a fost versiunea 3.1.0. Deoarece Firetruck utilizează versiunea 3.1.0 funcțională, puteți declara în condiții de siguranță o dependență Ladder versiunea 3.1.0, dar mai puțin decât 4.0.0. Acum, atunci când sunt disponibile Ladder 3.1.1 și 3.2.0 versiune, puteți integra în sistemul dvs. și să știe că acesta va fi compatibil cu funcționalitatea curentă.

Ca dezvoltator responsabil, cu siguranță doriți să fie sigur că toate actualizările funcționează după cum se menționează. În lumea reală o mizerie și nimic nu se poate face. Ce poți să faci - este da semantic Versionare oferă o metodă de fabricație, fără a comunicatelor de noi versiuni ale pachetelor dependente, și să economisiți timp și efort.

Dacă acest lucru sună tentant, tot ceea ce ai nevoie - este de a începe să utilizeze semantic Versionare, anunța că utilizați și urmați regulile. Adăugați un link la acest site în README, atunci utilizatorii vor ști regulile și de a culege beneficiile.

Ce ar trebui să fac cu revizuirile în 0.y.z la etapa inițială de dezvoltare?

Cel mai simplu lucru - pentru a începe dezvoltarea cu 0.1.0 și apoi crește versiunea minoră pentru fiecare eliberare ulterioară.

Cum știu când este timpul pentru a face 1.0.0 de eliberare?

Dacă software-ul este folosit pentru prodakshene, acesta poate fi deja 1.0.0. Dacă aveți un API stabil, utilizatorii depind de versiunea pe care ar trebui să fie 1.0.0. Dacă sunteți îngrijorat pentru compatibilitatea inversă este probabil versiunea software-ul este deja 1.0.0.

Are acest lucru împiedică dezvoltarea rapidă și iterațiile scurte?

Major Versiunea 0 înseamnă doar dezvoltarea rapidă. Dacă modificați API-ul în fiecare zi, ar trebui să fie pe versiunea 0.y.z sau pe o ramură separată a lucrărilor de dezvoltare în următoarea versiune majoră.

Chiar dacă cele mai mici modificări incompatibile înapoi la API publice necesită lansarea de noi versiuni majore, nu sa terminat dacă este faptul că foarte curând va fi versiunea 42.0.0?

Este o chestiune de dezvoltare responsabilă și de previziune. Schimbări incompatibile nu ar trebui să fie prezentat ca un minor în software-ul, care are o mulțime de cod specific. renovare costul poate fi ridicat. Practica de creștere majore versiuni versiune cu back incompatibil modificări înseamnă că trebuie să se gândească la consecințele modificărilor și să ia în considerare raportul calitate / pret.

Toate API Documentarea - prea mult de lucru!

Este responsabilitatea dumneavoastră ca un dezvoltator profesionist, software-ul corespunzător documentat proiectat pentru utilizarea pe scară largă. complexitatea gestionării o parte foarte importantă pentru a sprijini eficiența ridicată a proiectului. Este greu de făcut în cazul în care nimeni nu știe cum să folosească software-ul, sau orice metodă poate fi numit în condiții de siguranță. Pe termen lung semantic Versionare și persistența în documentarea calității API publice va ajuta pe toți și totul rula fără probleme.

Ce trebuie să fac dacă am accidental schimbări incompatibile în sens invers nelansate ca o versiune minoră?

De îndată ce vă dați seama că ați rupt caietul de sarcini semantic Versionare, corectați problema și a lansat o nouă versiune minoră, care corectează problema și restabilește compatibilitatea cu versiunile anterioare. Chiar și în aceste condiții, este inacceptabil să se modifice versiuni deja emise. Dacă este necesar să se precizeze în documentația de încălcare a compatibilitate inversă, versionare și informează utilizatorii, astfel încât aceștia să știe despre încălcarea ordinii versiunilor.

Ce ar trebui să fac dacă am actualiza propria mea, fără funcție de schimbările din API-ul public?

Ce se întâmplă dacă am schimbat accidental API-ul public din nerespectarea modificarea numărului versiunii (de exemplu, codul conține modificări incompatibile înapoi la eliberarea de patch-uri)?

La discreția dumneavoastră. Dacă aveți un public foarte mare, care va fi pus înainte API-ul returnează faptul comportament vechi, este mai bine pentru a elibera o nouă versiune cu o creștere în versiunea principală, în ciuda faptului că fix conține remedieri la nivel de patch-uri. Amintiți-vă, în număr de versiune semantică Versionare variază strict în urma caietul de sarcini. În cazul în care aceste modificări sunt importante pentru utilizatorii dvs., utilizați numărul versiunii pentru a le informa.

Ce se poate face cu funcționalitate învechită?

Există o versiune SemVer limite privind lungimea șirului?

Nu, dar cu bun simț. 255 de caractere pe linie versiune este, probabil, nejustificată. În plus, anumite sisteme pot impune propriile limite privind dimensiunea șirului.

Dacă doriți să lăsați un comentariu, vă rugăm să faceți o cerere de GitHub.