Սեմանտիկ Տարբերակում 2.0.0

Համառոտ

Այս ֆորմատով ներկայացված տարբերակի համարի (version number) դեպքում՝ ՄԱԺՈՐ․ՄԻՆՈՐ․ՓԱԹՉ (MAJOR.MINOR.PATCH), պետք է մեծացնել՝

  1. ՄԱԺՈՐ տարբերակի համարը, երբ տեղի են ունեցել API֊ի այնպիսի փոփոխություններ, որոնց արդյունքում խախտվել է հետ համատեղելիությունը։
  2. ՄԻՆՈՐ տարբերակի համարը, երբ ավելացվել է նոր ֆունկցիոնալ՝ հետ համատեղելիությունը չխախտելով (backwards-compatible)։
  3. ՓԱԹՉ տարբերակի համարը, երբ տեղի են ունեցել հետ համատեղելի փոփոխություններ։

Կարելի է անել նաև հավելյալ նշանակումներ՝ որպես հավելում ՄԱԺՈՐ․ՄԻՆՈՐ․ՓԱԹՉ ֆորմատին․ մինչթողարկումային (pre-release) պիտակ (label) և բիլդ-մետատվյալ (build metadata)։

Ներածություն

Ծրագրային ապահովման մենեջմենթի աշխարհում գոյություն ունի «կախվածությունների դժոխք» (dependency hell) հասկացություն։ Ձեր համակարգի մեծացման և դրան ինտեգրված փեքիջների քանակի ավելացման հետ մեծանում է հավանականությունը, որ դուք վաղ թե ուշ
կկանգնեք այս խնդրի առաջ։

Այն համակարգերում, որոնք ունեն շատ կախվածություններ, նոր տարբերակի թողարկումը կարող է արագ վերածվել մղձավանջի։ Եթե կախվածությունների սպեցիֆիկացիան շատ խիստ է, դուք կարող եք կանգնել նոր տարբերակի թողարկման արգելքի (version lock) առաջ (անհնար է դառնում թարմացնել ծրագիրը՝ առանց թարմացնելու կախման մեջ գտնվող բոլոր փեքիջները)։ Մյուս կողմից էլ, եթե կախվածությունների սպեցիֆիկացիան շատ ազատ է, դուք անխուսափելիորեն կբախվեք տարբերակի անհամապատասխանության (version promiscuity) խնդրին․ անհիմն է ենթադրությունը, որ ձեր ծրագիրը կմնա համատեղելի ապագա տարբերակների հետ։ «Կախվածությունների դժոխքը» մի իրավիճակ է, երբ տարբերակի թողարկման և/կամ տարբերակի անհապատասխանության արգելքը թույլ չի տալիս ձեզ հեշտ և անվտանգ զարգացնել ձեր նախագիծը։

Որպես այս խնդրի լուծում՝ ես առաջարկում եմ պարզ կանոններ և պահանջներ, որոնք սահմանում են, թե ինչպես են սահմանվում և մեծացվում տարբերակների համարները։ Այս կանոնները հիմնված են (բայց ոչ անպայման սահմանափակված) բաց (open source) և փակ (closed source) ծրագրային ապահովման գոյություն ունեցող և լայն տարածում գտած պրակտիկաների վրա։ Նախևառաջ, որպեսզի այս կանոններն աշխատեն, դուք պետք է սահմանեք փաբլիք API: Այն կարող է նկարագրված լինել ինչպես դոկումենտացիայի, այնպես էլ կոդի մեջ։ Կարևոր է, որ API֊ը լինի ճիշտ և հասկանալի։ Ձեր API֊ը հայտարարելուց հետո դուք փոփոխությունների մասին կտեղեկացնեք տարբերակի համարը մեծացնելու միջոցով։ Դիտարկենք այս ֆորմատով ներկայացված տարբերակ՝ X.Y.Z (ՄԱԺՈՐ․ՄԻՆՈՐ․ՓԱԹՉ)։ Սխալների ուղղումները (bug fix), որոենք չեն ազդել API-ի վրա, մեծացնում են ՓԱԹՉ֊ը։ Հետ համատեղելի հավելումները և փոփոխությունները մեծացնում են ՄԻՆՈՐ֊ը, հետ համատեղելիությունը խախտող փոփոխությունները մեծացնում են ՄԱԺՈՐ֊ը։

Ես անվանել եմ այս համակարգը «Սեմանտիկ տարբերակում» (Semantic Versioning): Այս սխեմայի միջոցով տարբերակի համարը և դրա փոխվելը իմաստավորում են կոդի պարունակությունը և նրանում եղած փոփոխությունները տարբերակից տարբերակ։

Սեմանտիկ տարբերակման սպեցիֆիկացիա (SemVer)

Նշված բառերը՝ «ՊԵՏՔ Է» (MUST, SHALL), «ՉՊԵՏՔ Է» (MUST NOT, SHALL NOT), «ՊԱՐՏԱԴԻՐ Է» (REQUIRED), «ԱՆՀՐԱԺԵՇՏ Է» (SHOULD), «ԱՆՀՐԱԺԵՇՏ ՉԷ» (SHOULD NOT), «ԽՈՐՀՈՒՐԴ Է ՏՐՎՈՒՄ» (RECOMMENDED), «ԿԱՐՈՂ Է» (MAY) և «ՊԱՐՏԱԴԻՐ ՉԷ» (OPTIONAL) պետք է ինտերպրիտացվեն RFC 2119 ստանդարտին համապատասխան։

  1. Ծրագրային ապահովումը, որն օգտագործվում է Սեմանտիկ տարբերակում, ՊԵՏՔ Է (MUST) հայտարարի հասանելի փաբլիք API: Այդ API֊ը կարող է հայտարարվել ինչպես կոդի մեջ, այնպես էլ՝ առանձին դոկումենտացիայում։ Երկու դեպքում էլ այն պետք է լինի ճշգրիտ (precise) և սպառիչ (comprehensive)։

  2. Տարբերակի ՆՈՐՄԱԼ համարը (normal version) ՊԵՏՔ Է (MUST) ունենա այս ֆորմատը՝ X.Y.Z, որտեղ X, Y և Z թվերը ոչ բացասական ամբողջ թվեր են և ՉՊԵՏՔ է (MUST NOT) սկսվեն զրոյով։ X֊ը տարբերակի ՄԱԺՈՐ համարն է, Y֊ը՝ ՄԻՆՈՐ և Z֊ը՝ ՓԱԹՉ։ Բոլոր բաղադիրչները պետք է մեծացվեն թվայնորեն․ օրինակ՝ 1.9.0 -> 1.10.0 -> 1.11.0։

  3. Փեքիջի թողարկումից հետո այդ տարբերակի պարունակությունը ՉՊԵՏՔ է (MUST NOT) փոփոխության ենթարկվի։ Ցանկացած փոփոխություն ՊԵՏՔ Է (MUST) թողարկվի որպես նոր տարբերակ։

  4. Զրոյական ՄԱԺՈՐ տարբերակը (0.y.z) նախատեսված է ծրագրային ապահովման ստեղծման/մշակման նախնական փուլի (initial development) համար։ Ամեն ինչ կարող է փոխվել՝ կամայական պահի։ Փաբլիք API֊ը չպետք է դիտարկվի որպես ստաբիլ։

  5. 1.0.0 տարբերակի թողարկումից հետո API-ը համարվում է ստաբիլ, և տարբերակի համարը փոխվում է կախված նրանից, թե ինչպես է փոխվում փաբլիք API֊ը։

  6. Տարբերակի ՓԱԹՉ համարը՝ Z (x.y.Z | x > 0), ՊԵՏՔ Է (MUST) մեծացվի, եթե տեղի են ունեցել միայն հետ համատեղելի սխալների ուղղումներ (bug fix)։ Սխալի ուղղում՝ նշանակում է ներքին փոփոխություն, որը ուղղում է սխալ պահվածքը։

  7. Տարբերակի ՄԻՆՈՐ համարը՝ Y (x.Y.z | x > 0), ՊԵՏՔ Է (MUST) մեծացվի, եթե փաբլիք API֊ում ավելացել է նոր հետ համատեղելի ֆունկցիոնալ։ Տարբերակի համարը ՊԵՏՔ Է (MUST) մեծացվի, եթե հասանելի փաբլիք API֊ի որևէ ֆունկցիոնալ պիտակավորվել է որպես հնացած (deprecated)։ Տարբերակի համարը ԿԱՐՈՂ Է (MAY) մեծացվել, եթե տեղի է ունեցել նոր ֆունկցիոնալի ինտեգրացիա, կամ զգալի բարելավումներ են տեղի ունեցել փրայվիթ կոդում։ Այն ԿԱՐՈՂ Է (MAY) նաև պարունակել ՓԱԹՉ մակարդակի փոփոխություններ։ Տարբերակի ՓԱԹՉ համարը ՊԵՏՔ Է (MUST) զրոյացվի, երբ մեծացվում է ՄԻՆՈՐ համարը։

  8. Տարբերակի ՄԱԺՈՐ համարը՝ X (X.y.z | X > 0), ՊԵՏՔ Է (MUST) մեծացվի, եթե փաբլիք API֊ում ներկայացվել են հետ համատեղելիությունը խախտող կամայական փոփոխություններ։ Այն ԿԱՐՈՂ Է (MAY) պարունակել նաև ՓԱԹՉ և ՄԻՆՈՐ մակարդակի փոփոխություններ։ Տարբերակի ՓԱԹՉ և ՄԻՆՈՐ համարները ՊԵՏՔ Է (MUST) զրոյացվեն, երբ մեծացվում է ՄԱԺՈՐ համարը։

  9. Մինչթողարկումային (pre-release) տարբերակը ԿԱՐՈՂ Է (MAY) պիտակավորվել տարբերակի ՓԱԹՉ համարից անմիջապես հետո գծիկ և դրան հետևող կետիկով առանձնացված տարբեր իդենտիֆիկատորներ ավելացնելու միջոցով։ Իդենտիֆիկատորները ՊԵՏՔ Է (MUST) պարունակեն միայն ASCII տառա֊թվային սիմվոլներ և գծիկ՝ [0-9A-Za-z-]։ Իդենտիֆիկատորները ՉՊԵՏՔ Է (MUST NOT) լինեն դատարկ։ Թվային իդենտիֆիկատորները ՉՊԵՏՔ Է (MUST NOT) սկսվեն զրոյով։ Մինչթողարկումային տարբերակները ունեն ավելի ցածր ԿԱՐԳԱՎԻՃԱԿ, քան համապատասխան ՆՈՐՄԱԼ֊ները։ Մինչթողարկումային տարբերակը ցույց է տալիս, որ այդ տարբերակը ստաբիլ չէ և կարող է չբավարարել համատեղելիության պահանջները, որոնք նշված են համապատասխան ՆՈՐՄԱԼ տարբերակում․ օրինակ՝ 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92։

  10. Բիլդ֊մետատվյալները (build-metadata) ԿԱՐՈՂ ԵՆ (MAY) պիտակավորվել տարբերակի ՓԱԹՉ համարից կամ մինչթողարկումային տարբերակի իդենտիֆիկատորից անմիջապես հետո գումարման նշան և դրան հետևող կետիկով առանձնացված տարբեր իդենտիֆիկատորներ ավելացնելու միջոցով։ Իդենտիֆիկատորները ՊԵՏՔ Է (MUST) պարունակեն միայն ASCII տառա֊թվային սիմվոլներ և գծիկ՝ [0-9A-Za-z-]։ Իդենտիֆիկատորները ՉՊԵՏՔ Է (MUST NOT) լինեն դատարկ։ Բիլդ֊մետատվյալները ՊԵՏՔ Է (MUST) անտեսել տարբերակի ԿԱՐԳԱՎԻՃԱԿԸ որոշելիս այսինքն, եթե նույն ծրագրի երկու տարբերակները տարբերվում են միայն բիլդ֊մետատվյալներով, ուրեմն դրանք ունեն նույն ԿԱՐԳԱՎԻՃԱԿԸ․ օրինակ՝ 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85։

  11. ԿԱՐԳԱՎԻՃԱԿԸ (precedence) որոշում է, թե ինչպես է պետք համեմատել տարբերակները միմյանց հետ, երբ դրանք դասավորված են։ ԿԱՐԳԱՎԻՃԱԿԸ ՊԵՏՔ Է (MUST) հաշվել տարբերակի համարը՝ ՄԱԺՈՐ, ՄԻՆՈՐ, ՓԱԹՉ, և մինչթողարկումային իդենտիֆիկատորները բաժանելու միջոցով։ ԿԱՐԳԱՎԻՃԱԿԸ որոշելիս բիլդ֊մետատվյալները հաշվի չեն առնվում։ ԿԱՐԳԱՎԻՃԱԿԸ որոշվում է ՄԱԺՈՐ, ՄԻՆՈՐ, ՓԱԹՉ տարբերակի համարները ձախից աջ թվայնորեն համեմատելու միջոցով․ օրինակ՝ 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1։ Երբ ՄԱԺՈՐ, ՄԻՆՈՐ և ՓԱԹՉ տարբերակի համարները հավասար են, մինչթողարկումային տարբերակը ունենում է ավելի փոքր ԿԱՐԳԱՎԻՃԱԿ, քան ՆՈՐՄԱԼ տարբերակը․ օրինակ՝ 1.0.0-alpha < 1.0.0։ Երբ տարբերակների ՄԱԺՈՐ, ՄԻՆՈՐ և ՓԱԹՉ համարները հավասար են, ԿԱՐԳԱՎԻՃԱԿԸ ՊԵՏՔ Է (MUST) որոշել մինչթողարկումային տարբերակի միջոցով՝ ձախից աջ կետով առանձնացված իդենտիֆիկատորները համեմատելով մինչև առաջին տարբերող իդենտիֆիկատոր գտնելը։ Մինչթողարկումային տարբերակները համեմատվում են տվյալ եղանակով՝ իդենտիֆիկատորները, որոնք կազմված են միայն թվերից, համեմատվում են թվայնորեն։ Տառեր և գծիկ պարունակող իդենտիֆիկատորները համեմատվում են տառացի՝ 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։

Բակուս֊Նոյերի սխեման SemVer֊ով ներկայացված տարբերակի համարների համար

<valid semver> ::= <version core>
                 | <version core> "-" <pre-release>
                 | <version core> "+" <build>
                 | <version core> "-" <pre-release> "+" <build>

<version core> ::= <major> "." <minor> "." <patch>

<major> ::= <numeric identifier>

<minor> ::= <numeric identifier>

<patch> ::= <numeric identifier>

<pre-release> ::= <dot-separated pre-release identifiers>

<dot-separated pre-release identifiers> ::= <pre-release identifier>
                                          | <pre-release identifier> "." <dot-separated pre-release identifiers>

<build> ::= <dot-separated build identifiers>

<dot-separated build identifiers> ::= <build identifier>
                                    | <build identifier> "." <dot-separated build identifiers>

<pre-release identifier> ::= <alphanumeric identifier>
                           | <numeric identifier>

<build identifier> ::= <alphanumeric identifier>
                     | <digits>

<alphanumeric identifier> ::= <non-digit>
                            | <non-digit> <identifier characters>
                            | <identifier characters> <non-digit>
                            | <identifier characters> <non-digit> <identifier characters>

<numeric identifier> ::= "0"
                       | <positive digit>
                       | <positive digit> <digits>

<identifier characters> ::= <identifier character>
                          | <identifier character> <identifier characters>

<identifier character> ::= <digit>
                         | <non-digit>

<non-digit> ::= <letter>
              | "-"

<digits> ::= <digit>
           | <digit> <digits>

<digit> ::= "0"
          | <positive digit>

<positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"

<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
           | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
           | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"
           | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"
           | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
           | "y" | "z"

Ի՞նչու օգտագործել սեմանտիկ տարբերակում

Սա նոր կամ հեղափոխական միտք չէ։ Հավանական է՝ դուք օգտվում եք տարբերակման նման ինչ֊որ եղանակից։ Խնդիրն այն է, որ «նման» եղանակից օգվելը կարող է բավարար չլինել։ Առանց կոշտ սպեցիֆիկացիայի տարբերակի համարները անօգուտ են դառնում կախվածությունները կարգավորելու հարցում։ Տալով անուն և որոշակիացնելով վերը ձևակերպված մտքերը՝ ավելի հեշտ է դառնում հաղորդել ձեր մտքերը այն օգտատերերին, որոնք օգտվում են ձեր ծրագրային ապահովումից։ Եթե այդ մտքերը հասկանալի են և ճկուն, կախվածությունների սպեցիֆիկացիան կաշխատի։

Պարզ օրինակի միջոցով կարելի է ցույց տալ, թե ինչպես է Սեմանտիկ Տարբերակումը «կախվածություննեի դժողքը» թողնում անցյալում։ Պատկերացնենք մի գրադարան (library), որի անունն է՝ «Firetruck»։ Նրա աշխատանքի համար անհրաժեշ է Սեմանտիկ Տարբերակումով թողարկվող «Ladder» փեքիջը։ Երբ Firetruck֊ը ստեղծվել էր, Ladder֊ի տարբերակի համարն էր՝ 3.1.0։ Քանի որ Firetruck֊ը օգտագործում է Ladder֊ի 3.1.0 տարբերակի ֆունկցիոնալը, դուք հանգիստ կարող եք հայտարարել կախվածությունը Ladder֊ի 3.1.0 տարբերակից, բայց ոչ ավել քան 4.0.0։ Երբ դուրս գա Ladder֊ի 3.2.0 տարբերակը, դուք հաստատ կիմանաք, որ այն համատեղելի է ձեր ծրագրի հետ և կարող եք հանգիստ ինտեգրել այն։

Որպես պատասխանատու ծրագրավորող՝ դուք իհարկե կցանկանաք վստահ լինել, որ բոլոր թարմացումները աշխատում են այնպես ինչպես հայտարարվել է։ Իրական աշխարհում միշտ խառնաշփոթ է, և ոչինչ չի կարելի անել դրա հետ, բացի ուշադիր լինելուց։ Սեմանտիկ տարբերակման միջոցով դուք կարող եք թողարկել ձեր ծրագրային ապահովման նոր տարբերակներ և թարմացումներ չմտածելով կախվածությունների մասին և պահպանել ձեր ժամանակը և նյարդերը։

Եթե այս ամենը գայթակղիչ է թվում ձեզ, այն ամենը ինչ ձեզ անհրաժեշտ է՝ սկսել օգտագործել Սեմանտիկ տարբերակումը, հայտարարել դրա մասին և հետևել կանոններին։ Նշեք այս կայքի հղումը ձեր README֊ում և օգտագործողները կիմանան այս կանոնների մասին։

ՀՏՀ

Ի՞նչ է անհրաժեշտ անել 0.y.z տարբերակում արված փոփոխությունների հետ, ծրագրավորման նախնական փուլում։

Ամենահեշտ լուծումը աշխատանքը 0.1.0 տարբերակի թողարկումով սկսելն է և հետագայում ամեն հաջորդ թողարկման համար ՄԻՆՈՐ տարբերակի համարը մեծացնելը։

Ի՞նչպես իմանալ, որ 1.0.0 տարբերակը թողարկելու ժամանկն է։

Եթե ձեր ծրագրային ապահովումը արդեն օգտագործվում է պրոդաքշնում, ամենայն հավանականությամբ արդեն պետք է թողարկել 1.0.0 տարբերակը։ Եթե դուք ունեք ստաբիլ API, որը ունի օգտագործողներ, տարբերակի համարը պետք է լինի 1.0.0։ Եթե անհանգստանում եք հետ համատեղելիության մասին, ամենայն հավանականությամբ ձեր ծրագրային ապահովման տարբերակի համարը արդեն պետք է լինի 1.0.0։

Արդյո՞ք աշխատելու այս ձևը չի խանգարում արագ ծրագրավորմանը (rapid development) և արագ իտերացիաներին (fast iteration)։

Երբ ՄԱԺՈՐ տարբերակի համարը 0 է, դա արդեն իսկ ենթադրում է արագ ծրագրավորում։ Եթե դուք փոփոխեք API֊ը ամեն օր, ապա պետք է լինեք 0.y.z տարբերակի վրա, կամ առանձին ճյուղի (branch) վրա աշխատեք հաջորդ ՄԱԺՈՐ տարբերակի թողարկման համար։

Եթե նույնիսկ փոքր փոփոխությունները, որոնք խախտում են հետ համատեղելիությունը, պահանջում են նոր ՄԱԺՈՐ տարբերակի թողարկում, արդյո՞ք դա չի հանգեցնի նրան, որ շուտով տարբերակի համարը դառնա 42.0.0։

Սա ավելի շատ պատասխանատվության և հեռատեսության խնդիր է։ Ծրագրային ապահովման հետ համատեղելիությունը խախտող փոփոխությունները աննշան չեն, քանի որ դրա արդյունքում թարմացումները կարող են շատ թանկ արժենալ։ Հետ համատեղելիությունը խախտող փոփոխությունների թողարկումը տարբերակի ՄԱԺՈՐ համարի ավելացմամբ, նշանակում է՝ դուք պետք է մտածեք ձեր փոփոխությունների հետևանքների մասին և հաշվի առնեք գին֊օգուտ հարաբերակցությունը։

Դոկումենտացիայի կազմումը մեծ աշխատանք է պահանջում։

Որպես պրոֆեսիոնալ ծրագրավորող ձեր պատասխանատվությունն է ճիշտ դոկումենտացնել ծրագրային ապահովումը, որը նախատեսված է ուրիշների օգտագործման համար։ Ծրագրային ապահովման բարդության կարգավորումը նրա արդյունավետության պահպանման կարևոևագույն կետերից մեկն է։ Եթե ոչ մեկը չգիտի, թե ինչպես օգտագործել ձեր ծրագրային ապահովումը, կամ որ մեթոդի կանչն է անվտանգ, ինչպես պետք է նրանք օգտագործեն այն։ Երկարաժամկետ հեռանկարով Սեմանտիկ Տարբերակումը, համառ և կոշտ դիրքը որակով շարադրված փաբլիք API֊ի նկատմամբ կնպաստեն ամենքի և ամեն ինչի ճիշտ և համակարգված աշխատելուն։

Ի՞նչ է անհրաժեշտ անել, եթե պատահաբար թողարկվել են հետ համատեղելիությունը խախտող փոփոխություններ ՄԻՆՈՐ տարբերակի տակ։

Հենց որ դուք հասկացաք, որ խախտել եք Սեմանտիկ Տարբերակման սպեցիֆիկացիան, ուղղեք սխալը և թողարկեք նոր ՄԻՆՈՐ տարբերակ, որը լուծում է խնդիրը և վերականգնում հետ համատեղելիությունը։ Նույնիսկ նման դեպքերում անընդունելի է արդեն թողարկված տարբերակներում փոփոխությունների իրականացումը։ Եթե անհրաժեշտ է, նշեք դոկումենտացիայում և տեղյակ պահեք օգտագործողներին հետ համատեղելիության և տարբերակման հերթականության խախտման մասին։

Ի՞նչ է անհրաժեշտ անել, եթե փոփոխվել են կախվածությունները առանց փաբլիք API֊ը փոփոխելու։

Դա կարող է դիտարկվել որպես հետ համատեղելի փոփոխություն, քանի որ այն չի ազդում փաբլիք API֊ի վրա։ Ծրագրային ապահովումը, որը ակնհայտորեն ունի նույն կախվածությունները, ինչ փեքիջը, պետք է ունենա իր սեփական կախվածությունների սպեցիֆիկացիան, և հեղինակը տեղյակ կլինի ի հայտ եկած կոնֆլիկտների մասին։ Արդյոք տվյալ փոփոխությունները ՄԱԺՈՐ, թե ՓԱԹՉ մակարդակի են, կախված է նրանից, թե դուք փոխել եք ձեր կախվածությունները սխալներ ուղղելու, թե՞ նոր ֆունկցիոնալ ինտեգրելու համար։ Երկրորդ դեպքում, որպես կանոն ավելանում է որոշակի քանակով կոդ և որպես հետևանք մեծանում է տարբերակի ՄԻՆՈՐ համարը։

Ի՞նչ անել, եթե պատահաբար փոփոխվել է փաբլիք API֊ը, և այն չի համապատասխանում տարբերակի համարին (այսինքն՝ կոդը սխալմամբ պարունակում է հետ համատեղելիությունը խախտող փոփոխություններ ՓԱԹՉ տարբերակի թողարկման մեջ)։

Որոշումը ձերն է։ Եթե դուք ունեք օգտագործողների մեծ խումբ, որը կկանգնի փաբլիք API֊ի նախկին ֆունկցիոնալի վերականգման փաստի առաջ, ուրեմն ճիշտ կլինի թողարկել նոր տարբերակ ՄԱԺՈՐ համարի մեծացումով։ Չնայած նրան, որ այն պարունակում է միայն ՓԱԹՉ մակարդակի փոփոխություններ, հիշեք՝ ըստ Սեմանտիկ Տարբերակման սպեցիֆիկացիայի տարբերակի համարները մեծացվում են սպեցիֆիկացիային համաձայն։ Եթե այդ փոփոխությունները կարևոր են ձեր օգտագործողների համար, օգտագործեք տարբերակի համարը նրանց տեղյակ պահելու համար։

Ի՞նչ անել հնացած (deprecated) ֆունկցիոնալի հետ։

Որոշ ֆունկցիոնալի հնանալը սովորական երևույթ է և ծրագրային ապահովման ստեղծման/մշակման ընթացքում հաճախ պարտադիր է առաջընթացի համար։ Երբ դուք հնացած եք հայտարարում, փաբլիք API֊ի ինչ֊որ հատված, դուք պետք է երկու բան անեք․ նախ թարմացնեք ձեր դոկումենտացիան և տեղեկացնեք օգտագործողներին փոփոխության մասին (1), և ապա թողարկեք նոր ՄԻՆՈՐ տարբերակ՝ նշում կատարելով հնացած ֆունկցիոնալի մասին (2)։ Մինչ դուք ամբողջովին կջնջեք հնացած ֆունկցիոնալը, հաջորդ ՄԱԺՈՐ թողարկման ժամանակ պետք է լինի առնվազն մեկ ՄԻՆՈՐ թողարկում, որը պարունակում է տեղեկություն ֆունկցիոնալի հնացած հայտարարվելու մասին, որպեսզի օգտագործողները հեշտությամբ անցնեն նոր API֊ի։

Արդյոք SemVer֊ը ունի՞ սահմանափակում տարբերակի համարի երկարության վրա։

Ոչ, բայց եղեք խելամիտ։ Եթե տարբերակի համարի երկարությունը 255 սիմվոլ է, հավանաբար դա չափազանց է։ Բացի դրանից որոշ համակարգեր կարող են ունենալ իրենց սեփական սահմանափակումները տարբերակի համարի երկարության վրա։

«v1.2.3» ֆորմատը համարվու՞մ է տարբերակի սեմանտիկ համար։

Ոչ, «v1.2.3»֊ը տարբերակի սեմանտիկ համար չի համարվում։ Ամեն դեպքում «v» տառը սեմանտիկ տարբերակի առջևում դնելը ընդունված երևույթ է (անգլերենում) տարբերակի համարը ընդգծելու համար։ «v» հապավման օգտագործումը «version» բառի փոխարեն տարածված պրակտիկա է տարբերակների կարգավորման (version control) մեջ: Օրինակ՝ git tag v1.2.3 -m "Release version 1.2.3"․ այստեղ «v1.2.3»֊ը թեգի անուն է, և սեմանտիկ տարբերակը «1.2.3» է։

Ինչպիսի՞ ռեգուլյար արտահայտության (RegEx) միջոցով կարելի է ստուգել SemVer տարբերակի համարի ճշտությունը:

Կա երկու եղանակ.

1) անվանական խմբերի միջոցով (named groups)։ (PCRE [Perl համատեղելի ռեգուլյար արտահայտություններ, օրինակ՝ Perl, PHP և R], Python և Go)։

Տես՝ https://regex101.com/r/Ly7O1x/3/

^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

2) թվային խմբերի (numbered capture groups) միջոցով (cg1 = major, cg2 = minor, cg3 = patch, cg4 = prerelease and cg5 = buildmetadata)։ Այս եղանակը համատեղելի է ECMA Script֊ի (JavaScript), PCRE֊ի (Perl համատեղելի ռեգուլյար արտահայտություններ, օրինակ՝ Perl, PHP և R), Python և Go.

Տես՝ https://regex101.com/r/vkijKf/1/

^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$

Հեղինակ

Սեմանտիկ Տարբերակման սպեցիֆիկացիայի հեղինակն է Թոմ Պրեստոն-Վարները (Gravatar֊ի հիմնադիր և GitHub֊ի համահիմնադիր)։

Եթե դուք ցանկանում եք որևէ մեկնաբանություն թողնել, խնդրում ենք GitHub֊ում հարց (issue) բացել։

Լիցենզիա

Creative Commons ― CC BY 3.0