mirror of
https://github.com/conventional-commits/conventionalcommits.org.git
synced 2024-11-15 02:45:15 +01:00
278 lines
19 KiB
Markdown
278 lines
19 KiB
Markdown
---
|
||
draft: false
|
||
aliases: ["/hy/"]
|
||
---
|
||
|
||
|
||
# Համաձայնեցված «Commit»֊ներ 1.0.0-beta.3
|
||
|
||
## Համառոտագիր
|
||
|
||
Համաձայնեցված «commit»֊ների սպեցիֆիկացիան կանոնների խումբ է «commit»
|
||
մեսիջների վերաբերյալ։ Այն առաջարկում է պարզ կանոններ և պահանջներ, որոնց միջոոցով
|
||
հնարավոր է ստանալ հասկանալի և ընթեռնելի «commit»֊ների պատմություն, և հեշտացնել
|
||
ավտոմատացված ծրագրային ապահովման ստեղծումը, որոնք աշխատում են «commit» մեսիջների
|
||
հիման վրա։ Այս կանոնները ուղիղ կապ ունեն
|
||
[SemVer](http://semver.org/#summary)֊ի սպեցիֆիկացիայի հետ, և օգատգործվում են նոր
|
||
ֆունցիոնալի ինտեգրման (features), սխալների ուղղումների (fixes) և հետ
|
||
համատեղելիությունը խախտող փոփոխությունների (bracking changes) մասին «commit»
|
||
մեսիջներում տեղելացնելու համար։
|
||
|
||
«commit» մեսիջները պետք է ունենան հետևյալ կառուցվածքը՝
|
||
|
||
---
|
||
|
||
```
|
||
<տեսակ (type)>[ոչ պարտադիր կոնտեքստ (optional scope)]: <բացատրություն (description)>
|
||
|
||
[ոչ պարտադիր մարմին (optional body)]
|
||
|
||
[ոչ պարտադիր ներքևի հատված (optional footer)]
|
||
```
|
||
---
|
||
|
||
«commit»֊ները պարունակում են հետևյալ ստրուկտուրալ էլեմենտները, որոնց միջոցով ձեր
|
||
ծրագրային ապահովման օգտագործողները կարող են հասկանալ ինչ է տեղի ունեցել
|
||
«commit»֊ների արդյունքում՝
|
||
|
||
1. **fix։**․ `fix` _ՏԵՍԱԿԻ_ «commit»֊ները նախատեված են սխալների ուղղումների (bug
|
||
fix) մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ տարբերակման մեջ
|
||
ներկայացված [`«ՓԱԹՉ»`](http://semver.org/#summary)֊ի հետ)։
|
||
|
||
2. **feat։**․ `feat` _ՏԵՍԱԿԻ_ «commit»֊ները նախատեված են նոր
|
||
ֆունկցիոնալի ինտեգրման մասին տեղեկացնելու համար (այն փոխկապակցված է սեմանտիկ
|
||
տարբերակման մեջ ներկայացված [`«ՄԻՆՈՐ»`](http://semver.org/#summary)֊ի հետ)։
|
||
|
||
3. **BREAKING CHANGE։**․ `BREAKING CHANGE։` պարունակող «commit»֊ները
|
||
(_ՄԱՐՄՆՈՒՄ_ կամ _ՆԵՐՔԵՎԻ ՀԱՏՎԱԾՈՒՄ_ ) տեղեկացնում են API֊ում արված փոփոխության
|
||
մասին, որը խախտում է հետ համատեղելիությունը (breaking changes) (այն փոխկապակցված
|
||
է սեմանտիկ տարբերակման մեջ ներկայացված [`ՄԱԺՈՐ`](http://semver.org/#summary)֊ի
|
||
հետ), `BREAKING CHANGE:`֊ը կարող է հանդիպել կամայական _ՏԵՍԱԿԻ_ «commit»֊ների հետ:
|
||
|
||
4. Ուրիշ տեսակներ. կարելի է օգտագործել նաև վերը նշվածներից տարբերվող
|
||
_ՏԵՍԱԿ_ ունեցող (`fix:` և `feat:`) «commit»֊ներ, օրինակ՝
|
||
[@commitlint-config-conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional)֊ը
|
||
(հիմնված է [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines)֊ի վրա)
|
||
առաջարկում է օգագործել են նաև՝ `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](http://tools.ietf.org/html/rfc2119) ստանդարտին
|
||
համապատասխան։
|
||
|
||
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`](http://semver.org/#summary)֊ից։
|
||
(Մենք խրախուսում ենք հավելվածների ստեղծումը)։
|
||
|
||
### Ինչ ես պետք է անեմ, երբ սխալմամբ «commit»֊ի սխալ _ՏԵՍԱԿ_ եմ օգտագործել։
|
||
|
||
#### Եթե ծեր օգտագործած _ՏԵՍԱԿԸ_ առկա է սպեցիֆիկացիայում, բայց այն սխալ է, օրինակ `fix`՝ `feat`֊ի փոխարեն։
|
||
|
||
Մինչ ձեր սխալը «mergе» անելը, կամ թողարկելը, խորհուրդ է տրվում օգտագործել
|
||
`git rebase -i` և փոփոխել commit»֊ների պատմությունը։ Թողարկելուց հետո, ուղղելու
|
||
եղանակները տարբեր են՝ կախված նրանից թե ինչ գործիքներից եք դուք օգտվում։
|
||
|
||
#### Եթե ձեր օգտագործած _ՏԵՍԱԿԸ_ առկա չէ սպեցիֆիկացիայում, օրինակ `feet`՝ `feat`֊ի փոխարեն։
|
||
|
||
Դա ամենևին էլ աշխարհի վերջը չէ։ Դա ուղղակի կնշանակի, որ ձեր սպեցիֆիկացիայի հիման վրա աշխատող գործիքներրը կանտեսեն այդ «commit»֊ը։
|
||
|
||
### Իմ բոլոր գործընկերները նույնպե՞ս պետք է հետևեն համաձայնեցված «commit»֊ների սպեցիֆիկացիային։
|
||
|
||
Ոչ․ եթե ձեր աշխատանքային պրոցեսը հիմնված է «squash»֊երի վրա՝ նախագծի ղեկավարը
|
||
կարող է մաքրել պատմությունը մինչև «mergе» անելը և ուշադրություն չդարձնել այդ ամենին։
|
||
Սովորաբար git֊ը ավտոմատ «squash» է անում «commit»֊ները PR֊ի ժամանակ և վերջին
|
||
«commit»֊ը անում է նախագծի ղեկավարը։
|
||
|
||
## Սպեցիֆիկացիայի Մասին
|
||
|
||
Համաձայնեցված «commit»֊ների սպեցիֆիկացիան ոգեշնչված է և ստեղծված
|
||
[Angular Commit Guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit)֊ի
|
||
հիման վրա։
|
||
|
||
Առաջին սևագիրը ստեղծվել է մի քանի մասնակիցների օգնությամբ։
|
||
|
||
* [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)․
|
||
գործիքների խումբ է, git֊ի պատմությունից hամաձայնեցված «commit»֊ները
|
||
առանձնացնելու համար։
|
||
* [parse-commit-message](https://github.com/olstenlarck/parse-commit-message)․
|
||
ծրագիր է, որը «commit»֊ից առանձնացնում է
|
||
`{ header: { type, scope, subject }, body, footer }` օբյեկտ:
|
||
* [bumped](https://bumped.github.io/)․ գործիք է, որի միջոցով կարելի է, որոշակի
|
||
գործողություններ կատարել ծրագրային ապահովումը հրապարակելուց առաջ կամ հետո։
|
||
* [unleash](https://github.com/netflix/unleash)․ գործիք, որը ավտոմատացնում է
|
||
ծրագրերի թողարկումը և հրապարակումը։
|
||
* [lerna](https://github.com/lerna/lerna)․ մոնո֊ռեպոզիտորիաների կառավարման
|
||
գործիք է, որը ստեղծվել է Babel֊ի հիման վրա։
|
||
|
||
## Գործիքներ՝ համածայնեցված «commit»֊ների համար
|
||
|
||
* [php-commitizen](https://github.com/damianopetrungaro/php-commitizen)․ գործիք,
|
||
որի միջոցով կարելի է ստեղծել «commit»֊ներ՝ համաձայնեցված «commit»֊ների
|
||
սպեցիֆիկացիային համաձայն։ Կարելի է օգտագործել PHP֊ով իրականացվող նախագծերում,
|
||
կամ առանձին։
|
||
* [conform](https://github.com/autonomy/conform)․ այս գործիքի միջոցով կարելի է
|
||
կազմակերպել կանոններ git ռեպոզիտորիաների համար, օրինակ համաձայնեցված
|
||
«commit»֊ների հիման վրա։
|
||
|
||
## Նախագծեր, որոնք օգտագործում են Համաձայնեցված «Commit»֊ներ
|
||
|
||
* [yargs](https://github.com/yargs/yargs)․ Բոլոր կողմից սիրված «command line»
|
||
արգումենտներ առանձնացնելու գործիք (parser)։
|
||
* [istanbuljs](https://github.com/istanbuljs/istanbuljs)․ Բաց կոդով գրադարանների
|
||
և գործիքների խումբ է, ձեր «JavaScript»֊ով ստեղծված ծրագրային ապահովման տեստերի
|
||
ընդգրկելիությունը որոշելու համար։
|
||
* [standard-version](https://github.com/conventional-changelog/standard-version):
|
||
Ավտոմատ տարբերակման և փոփոխությունների լոգի ստեղծում համաձայնեցված «commit»֊ների
|
||
հիման վրա։
|
||
* [uPortal-home](https://github.com/UW-Madison-DoIT/angularjs-portal) և
|
||
[uPortal-application-framework](https://github.com/UW-Madison-DoIT/uw-frame)․
|
||
[Apereo uPortal](https://www.apereo.org/projects/uportal)֊ի համար նախատեսված
|
||
UI֊ը բարելավելու գործիքներ։
|
||
* [massive.js](https://github.com/dmfay/massive-js)․ Տվյալների հետ աշխատելու
|
||
համար նախատեսված գրադարան Node֊ի և PostgreSQL֊ի համար։
|
||
* [electron](https://github.com/electron/electron)․ Քրոս֊պլատֆորմ, համակարգչային
|
||
ծրագրերի ստեղծման համար JavaScript, HTML, և CSS֊ով։
|
||
* [scroll-utility](https://github.com/LeDDGroup/scroll-utility)․ Անիմացիաների և
|
||
էլեմենտները տեղակայելու համար նախատեսված գործիք։
|
||
* [Blaze UI](https://github.com/BlazeUI/blaze)․ UI հավաքելու գործիք։
|
||
* [Monica](https://github.com/monicahq/monica): An open source personal
|
||
relationship management system.
|
||
* [mhy](https://mhy.js.org): A zero-config, out-of-the-box, multi-purpose
|
||
toolbox and development environment.
|
||
|
||
[](https://conventionalcommits.org)
|
||
|
||
_Ցանկանու՞մ եք տեսնել ձեր նախագիծը այս ցուցակում_ [ուղղարկեք «pull» հարցում](https://github.com/conventional-changelog/conventionalcommits.org/pulls)։
|