Համաձայնեցված «Commit»֊ներ 1.0.0-beta.4

Համառոտագիր

Համաձայնեցված «commit»֊ների սպեցիֆիկացիան կանոնների խումբ է «commit» մեսիջների վերաբերյալ։ Այն առաջարկում է պարզ կանոններ և պահանջներ, որոնց միջոոցով հնարավոր է ստանալ հասկանալի և ընթեռնելի «commit»֊ների պատմություն, և հեշտացնել ավտոմատացված ծրագրային ապահովման ստեղծումը, որոնք աշխատում են «commit» մեսիջների հիման վրա։ Այս կանոնները ուղիղ կապ ունեն SemVer֊ի սպեցիֆիկացիայի հետ, և օգատգործվում են նոր ֆունցիոնալի ինտեգրման (features), սխալների ուղղումների (fixes) և հետ համատեղելիությունը խախտող փոփոխությունների (bracking changes) մասին «commit» մեսիջներում տեղելացնելու համար։

«commit» մեսիջները պետք է ունենան հետևյալ կառուցվածքը՝

<տեսակ (type)>[ոչ պարտադիր կոնտեքստ (optional scope)]: <բացատրություն (description)>

[ոչ պարտադիր մարմին (optional body)]

[ոչ պարտադիր ներքևի հատված (optional footer)]

«commit»֊ները պարունակում են հետևյալ ստրուկտուրալ էլեմենտները, որոնց միջոցով ձեր ծրագրային ապահովման օգտագործողները կարող են հասկանալ ինչ է տեղի ունեցել «commit»֊ների արդյունքում՝

1. fix։․ fix ՏԵՍԱԿԻ «commit»֊ները նախատեված են սխալների ուղղումների (bug fix) մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված «ՓԱԹՉ»֊ի հետ)։

2. feat։․ feat ՏԵՍԱԿԻ «commit»֊ները նախատեված են նոր ֆունկցիոնալի ինտեգրման մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված «ՄԻՆՈՐ»֊ի հետ)։

3. BREAKING CHANGE։․ BREAKING CHANGE։ պարունակող «commit»֊ները (ՄԱՐՄՆՈՒՄ կամ ՆԵՐՔԵՎԻ ՀԱՏՎԱԾՈՒՄ ) տեղեկացնում են API֊ում արված փոփոխության մասին, որը խախտում է հետ համատեղելիությունը (breaking changes) (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ ներկայացված ՄԱԺՈՐ֊ի հետ), BREAKING CHANGE:֊ը կարող է հանդիպել կամայական ՏԵՍԱԿԻ «commit»֊ների հետ:

4. Ուրիշ տեսակներ. կարելի է օգտագործել նաև վերը նշվածներից տարբերվող ՏԵՍԱԿ ունեցող (fix: և feat:) «commit»֊ներ, օրինակ՝ @commitlint-config-conventional֊ը (հիմնված է Angular convention֊ի վրա) առաջարկում է օգագործել են նաև՝ chore:, docs:, style:, refactor:, perf:, test: և այլ ՏԵՍԱԿԻ «commit»֊ներ։

Մենք նաև առաջարկում ենք օգագործել improvement, այն ՏԵՍԱԿԻ «commit»֊ների համար, որոնք բարելավում են գործող իմպլեմենտացիան առանց նոր ֆունկցիոնալի ինտեգրման և սխալների ուղղման։ Ուշադրություն դարձրեք, որ «commit»֊ների այս ՏԵՍԱԿՆԵՐԸ չեն հանդիսանում համաձայնեցված «commit»֊ների սպեցիֆիկացիայի մաս և ոչ մի ձևով փոխկապակցված չեն սեմանտիկ տարբերակման սպեցիֆիկացիայի հետ (բացառություն են հանդիսանում BREAKING CHANGE: պարունակող «commit»֊ները)։

ԿՈՆՏԵՔՍՏ կարող է ավելացվել «commit»֊ի ՏԵՍԱԿԻՆ ՝ «commit»-ի կոնտեքստ սահմանելու նպատակով։ ԿՈՆՏԵՔՍՏԸ պետք է լինի փակագծերի մեջ օրինակ՝ feat(parser): add ability to parse arrays։

Օրինակներ

«commit», որը ունի ԲԱՑԱՏՐՈՒԹՅՈՒՆ և BREAKING CHANGE իր մարմնում

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

«commit», որում կա ! BREAKING CHANGE ֊ի վրա ուշադրություն գրավելու համար

chore!: drop Node 6 from testing matrix

BREAKING CHANGE: dropping Node 6 which hits end of life in April

«commit», որը չունի ՄԱՐՄԻՆ

docs: correct spelling of CHANGELOG

«commit», որը ունի ԿՈՆՏԵՔՍՏ

feat(lang): add polish language

«commit», սխալի ուղղման համար, որը պարունակում է առաջադրանքի (issue) համարը

fix: correct minor typos in code

see the issue for details on the typos fixed

closes issue #12

Սպեցիֆիկացիա

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

1. «commit» մեսիջները ՊԵՏՔ Է (MUST) սկսվեն ՏԵՍԱԿԻ (type) մասին նշումով, որը գոյական է (noun) և բաղկացած է լինում մեկ բառից՝ օրինակ՝ feat, fix, և այլն։ Դրան հետևում է ՈՉ ՊԱՐՏԱԴԻՐ (OPTIONAL) ԿՈՆՏԵՔՍՏԸ (scope) և ՊԱՐՏԱԴԻՐ (REQUIRED) վերջակետի նշանը և բացատը։

2. feat ՏԵՍԱԿԸ ՊԵՏՔ Է (MUST) օգտագործվի, երբ «commit»֊ի արդյունքում տեղի է ունենում նոր ֆունցիոնալի իմպլեմենտացիա ձեր ծրագրում կամ գրադարանում։

3. fix ՏԵՍԱԿԸ ՊԵՏՔ Է (MUST) օգտագործվի, երբ «commit»֊ի արդյունքում տեղի է ունենում սխալի ուղղում ձեր ծրագրում։

4. ԿՈՆՏԵՔՍՏԸ ԿԱՐՈՂ Է (MAY) ավելացվել ՏԵՍԱԿԻՑ անմիջապես հետո։ ԿՈՆՏԵՔՍՏԸ ՊԵՏՔ Է (MUST) գոյական լինի պարփակված փակագծերի մեջ, և նկարագրի կոդի այն հատվածը, որի վրա անդրադարձել է «commit»֊ը։ Օրինակ՝ fix(parser): ։

5. ԲԱՑԱՏՐՈՒԹՅՈՒՆԸ (description) ՊԵՏՔ Է (MUST) լինի անմիջապես ՏԵՍԱԿ/ԿՈՆՏԵՔՍՏ-ին հետևող բացատից հետո։ ԲԱՑԱՏՐՈՒԹՅՈՒՆԸ համառոտ ներկայանում է կոդում եղած փոփոխությունները։ Օրինակ՝ fix: array parsing issue when multiple spaces were contained in string։

6. ՄԱՐՄԻՆԸ (body) ԿԱՐՈՂ Է (MAY) հետևել կարճ ԲԱՑԱՏՐՈՒԹՅԱՆԸ և ավելի մեծ ինֆորմացիա տրամադրել կոդում եղած փոփոխությունների մասին։ ՄԱՐՄԻՆԸ ՊԵՏՔ Է (MUST) առանձնացվի ԲԱՑԱՏՐՈՒԹՅՈՒՆԻՑ մեկ դատարկ տողով։

7. ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԸ (footer) ԿԱՐՈՂ Է (MAY) լինել մեկ կամ մի քանի տողի տեսքով ՄԱՐՄՆԻՑ անմիջապես հետո և պետք է անջատված լինի ՄԱՐՄՆԻՑ մեկ դատարկ տողով։ ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԸ ՊԵՏՔ Է (MUST) պարունակի մետա֊ինֆորմացիա «commit»֊ի մասին, օրինակ՝ «pull» հարցումների, ստուգողների (reviewers), հետ համատեղելիությունը խախտող փոփոխությունների և ալյն։ Մետա֊ինֆորմացիայի ամեն մասը զբաղեցնում է մեկ տող։

8. Հետ համատեղելիությունը խախտող փոփոխությունները ՊԵՏՔ Է (MUST) պիտակավորվեն ՄԱՐՄԻՆԻ կամ ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԻ սկզբում։ Հետ համատեղելիությունը խախտող փոփոխությունները ՊԵՏՔ Է (MUST) պիտակավորվեն այս արտահայտությամբ՝ BREAKING CHANGE (պարտադիր մեծատառերով), որին հետևում է վերջակետ և բացատ։

9. Հետ համատեղելիությունը խախտող փոփոխությունների նկարագիրը (ինչ է փոխվել API-ում) ՊԵՏՔ Է (MUST) հետևեն BREAKING CHANGE: պիտակին։ Օրինակ՝ BREAKING CHANGE: environment variables now take precedence over config files.։

10. «commit»-ների ՏԵՍԱԿՆԵՐԸ ԿԱՐՈՂ ԵՆ (MAY) լինել feat֊ից և fix֊ից տարբեր։

11. Համաձայնեցված «commit»֊ներում ներկայացված բաղադրիչները, ՉՊԵՏՔ Է (MUST NOT) դիտարկվեն, որպես ռեգիստրից կախված (case sensitive), բացառություն է միայն BREAKING CHANGE֊ը, որը միշտ պետք է լինի մեծատառերով։

12. ! նշանը ԿԱՐՈՂ Է (MAY) ավելացվել : նշանից առաջ և ՏԵՍԱԿ/ԿՈՆՏԵՔՍՏ-ից հետո, որպեսզի ուշադրություն գրավի հետ համատեղելիությունը խախտող փոփոխությունների վրա։ BREAKING CHANGE: description տողը ևս ՊԵՏՔ Է (MUST) ավելացվի ՄԱՐՄԻՆԻ կամ ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԻ սկզբում, եթե օգտագործվել է ! նշանը։

Ի՞նչու օգտագործել Համաձայնեցված «Commit»֊ներ

• Փոփոխությունների լոգերի (CHANGELOG) ավտոմատ գեներացում։
• Սեմանտիկ տարբերակի ավտոմատ որոշում «commit»֊ի հիման վրա։
• Տեղեկացնել փոփոխությունների բնույթի մասին թիմի անդամներին, հասարակությանը և հետաքրքրված անձանց։
• Ավտոմատացնել կառուցման (build) և հրապարակման (publish) պրոցեսները։
• Հեշտացնում է նոր մասնակիցների ինտեգրումը ձեր նախագծին, հասանելի և ստրուկտուրիզացված «commit»֊ների պատմության շնորհիվ։

ՀՏՀ

Ի՞նչպես գրել «commit» մեսիջները աշխատանքի նախնական փուլերում (initial development phase):

Խորհուրդ է տրվում գրել մեսիջներն այնպես, կարծես դուք արդեն հրապարակել եք պրոդուկտը։ Որևէ մեկին ՝ օրինակ ձեր գործընկերներին կարող է հետաքրքիր լինել, թե ինչն է փոխվել, և ինչ նոր հետ համատեղելիությունը խախտող փոփոխություններ են եղել։

Ի՞նչ անել, եթե «commit»֊ը ունի ավելի քան մեկ ՏԵՍԱԿ։

Եթե հնարավոր է արեք իմ քանի «commit»։ Համաձայնեցված «commit»֊ների հիմնական առավելություններից մեկը՝ ավելի կազմակերպված «commit»֊ների և «PR»֊ների թողարկումն է։

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

Այս եղանակը խանգարում է ոչ կազմակերպված արագ աշխատանքին։ Դրա փոխարեն դուք արագ եք շարժվում երկարաժամկետ տեսլականով, մի քանի պրոյեկտի մասշտաբով և մի քանի մասնակիցներ առկայությամբ։

Արդյո՞ք համաձայնեցված «commit»֊ների ՏԵՍԱԿՆԵՐԸ չեն սահմանափակի ծրագրավորողներին, քանի որ նրանք պետք է մտածեն տրամադրված ՏԵՍԱԿՆԵՐԻ սահմաններում։

Համաձայնեցված «Commit»֊ների սպեցիֆիկացիան խրախուսում է այլ ՏԵՍԱԿԻ «commit»֊ների օգտագործումը։ Ձեր թիմը կարող է ազատ լինել իր սեփական ՏԵՍԱԿՆԵՐԻ ստեղծման մեջ և փոփոխել դրանք ժամանակի ընթացքում։

Ի՞նչ կապ ունի այս ամենը տարբերակման սեմանտիկ կանոնների՝ SemVer֊ի հետ։

fix ՏԵՍԱԿԻ «commit»֊ները թողարկվում են, որպես ՓԱԹՉ. feat ՏԵՍԱԿԻ «commit»֊ները թողարկվում են, որպես ՄԻՆՈՐ. BREAKING CHANGE պարունակող կամայական «commit», ՏԵՍԱԿԻՑ անկախ, թողարկվում է, որպես ՄԱԺՈՐ։

Ինչպե՞ս է պետք տարբերակել համաձայնեցված «commit»֊ների սպեցիֆիկացիայի հիման վրա ստեղծված իմ սեփական հավելվածերը, օրինակ՝ @jameswomack/conventional-commit-spec

Համաձայնեցված «commit»֊ների սպեցիֆիկացիայի հիման վրա ձեր հավելվածները ստեղծելիս և թողարկելիս, խորհուրդ է տրվում օգտվել՝ SemVer֊ից։ (Մենք խրախուսում ենք հավելվածների ստեղծումը)։

Ինչ ես պետք է անեմ, երբ սխալմամբ «commit»֊ի սխալ ՏԵՍԱԿ եմ օգտագործել։

Եթե ծեր օգտագործած ՏԵՍԱԿԸ առկա է սպեցիֆիկացիայում, բայց այն սխալ է, օրինակ fix՝ feat֊ի փոխարեն։

Մինչ ձեր սխալը «mergе» անելը, կամ թողարկելը, խորհուրդ է տրվում օգտագործել git rebase -i և փոփոխել commit»֊ների պատմությունը։ Թողարկելուց հետո, ուղղելու եղանակները տարբեր են՝ կախված նրանից թե ինչ գործիքներից եք դուք օգտվում։

Եթե ձեր օգտագործած ՏԵՍԱԿԸ առկա չէ սպեցիֆիկացիայում, օրինակ feet՝ feat֊ի փոխարեն։

Դա ամենևին էլ աշխարհի վերջը չէ։ Դա ուղղակի կնշանակի, որ ձեր սպեցիֆիկացիայի հիման վրա աշխատող գործիքներրը կանտեսեն այդ «commit»֊ը։

Իմ բոլոր գործընկերները նույնպե՞ս պետք է հետևեն համաձայնեցված «commit»֊ների սպեցիֆիկացիային։

Ոչ․ եթե ձեր աշխատանքային պրոցեսը հիմնված է «squash»֊երի վրա՝ նախագծի ղեկավարը կարող է մաքրել պատմությունը մինչև «mergе» անելը և ուշադրություն չդարձնել այդ ամենին։ Սովորաբար git֊ը ավտոմատ «squash» է անում «commit»֊ները PR֊ի ժամանակ և վերջին «commit»֊ը անում է նախագծի ղեկավարը։