conventionalcommits.org/content/v1.0.0-beta.3/index.hy.md

draft	aliases
false	/hy/

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

Համառոտագիր

Համաձայնեցված «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», որը չունի ՄԱՐՄԻՆ

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, և այլն։ Դրան հետևում է վերջակետի նշանը և բացատը։

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»֊ի մասին, (օրինակ Fixes #13):

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

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

10. ՆԵՐՔԵՎԻ ՀԱՏՎԱԾԻ ՊԵՏՔ Է (MUST) միայն պարունակի BREAKING CHANGE, արտաքին հղումներ, խնդրի մասին նշումներ և այլ մետատվյալներ։

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

Ի՞նչու օգտագործել Համաձայնեցված «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»֊ը անում է նախագծի ղեկավարը։

Սպեցիֆիկացիայի Մասին

Համաձայնեցված «commit»֊ների սպեցիֆիկացիան ոգեշնչված է և ստեղծված Angular Commit Guidelines֊ի հիման վրա։

Առաջին սևագիրը ստեղծվել է մի քանի մասնակիցների օգնությամբ։

• conventional-changelog․ գործիքների խումբ է, git֊ի պատմությունից hամաձայնեցված «commit»֊ները առանձնացնելու համար։
• parse-commit-message․ ծրագիր է, որը «commit»֊ից առանձնացնում է { header: { type, scope, subject }, body, footer } օբյեկտ:
• bumped․ գործիք է, որի միջոցով կարելի է, որոշակի գործողություններ կատարել ծրագրային ապահովումը հրապարակելուց առաջ կամ հետո։
• unleash․ գործիք, որը ավտոմատացնում է ծրագրերի թողարկումը և հրապարակումը։
• lerna․ մոնո֊ռեպոզիտորիաների կառավարման գործիք է, որը ստեղծվել է Babel֊ի հիման վրա։

Գործիքներ՝ համածայնեցված «commit»֊ների համար

• php-commitizen․ գործիք, որի միջոցով կարելի է ստեղծել «commit»֊ներ՝ համաձայնեցված «commit»֊ների սպեցիֆիկացիային համաձայն։ Կարելի է օգտագործել PHP֊ով իրականացվող նախագծերում, կամ առանձին։
• conform․ այս գործիքի միջոցով կարելի է կազմակերպել կանոններ git ռեպոզիտորիաների համար, օրինակ համաձայնեցված «commit»֊ների հիման վրա։

Նախագծեր, որոնք օգտագործում են Համաձայնեցված «Commit»֊ներ

• yargs․ Բոլոր կողմից սիրված «command line» արգումենտներ առանձնացնելու գործիք (parser)։
• istanbuljs․ Բաց կոդով գրադարանների և գործիքների խումբ է, ձեր «JavaScript»֊ով ստեղծված ծրագրային ապահովման տեստերի ընդգրկելիությունը որոշելու համար։
• standard-version: Ավտոմատ տարբերակման և փոփոխությունների լոգի ստեղծում համաձայնեցված «commit»֊ների հիման վրա։
• uPortal-home և uPortal-application-framework․ Apereo uPortal֊ի համար նախատեսված UI֊ը բարելավելու գործիքներ։
• massive.js․ Տվյալների հետ աշխատելու համար նախատեսված գրադարան Node֊ի և PostgreSQL֊ի համար։
• electron․ Քրոս֊պլատֆորմ, համակարգչային ծրագրերի ստեղծման համար JavaScript, HTML, և CSS֊ով։
• scroll-utility․ Անիմացիաների և էլեմենտները տեղակայելու համար նախատեսված գործիք։
• Blaze UI․ UI հավաքելու գործիք։
• Monica: An open source personal relationship management system.
• mhy: A zero-config, out-of-the-box, multi-purpose toolbox and development environment.

Ցանկանու՞մ եք տեսնել ձեր նախագիծը այս ցուցակում ուղղարկեք «pull» հարցում։