Համաձայնեցված «Commit»֊ներ

Սպեցիֆիկացիա, որը ընթեռնելի է դարձնում «commit» մեսիջները մեքենաների և մարդկանց համար

Conventional Commits 1.0.0

Ամփոփում

Conventional Commits-ը իրենից ներկայացնում է թեթև կոնվենցիաներ՝ commit հաղորդագրությունների վրա։ Այն ապահովում է պարզ commit-ների պատմություն ստեղծելու հեշտ եղանակ, ինչը հեշտացնում է ավտոմատացման գործիքների օգտագործումը։ Այս կոնվենցիան համընկնում է SemVer-ի հետ, նկարագրելով commit հաղորդագրություններում կատարված առանձնահատկությունները, ուղղումները և փոփոխությունները:

Commit հաղորդագրությունները պետք է ունենան հետևյալ կառուցվածքը․


<տիպ>[ոչ պարտադիր շրջանակ]: <նկարագրություն>

[ոչ պարտադիր մարմին]

[ոչ պարտադիր վերջավորություն(ներ)]

Commit-ը պարունակում է հետևյալ կառուցվածքային տարրերը՝ ձեր փոփոխությունների մտադրությունը հաղորդելու համար.

  1. fix: այն commit-ները, որոնք պատկանում են fix տիպին , իրենցից ներկայացնում են բագերի ուղղումներ (այն համապատասխանում է Semantic Versioning-ի PATCH տեսակին)։
  2. feat: այն commit-ները, որոնք պատկանում են feat տիպին , իրենցից ներկայացնում են նոր հատկանիշների ավելացում (այն համապատասխանում է Semantic Versioning-ի MINOR տեսակին)։
  3. BREAKING CHANGE: այն commit-ները, որոնք ունեն BREAKING CHANGE: վերջավորությունը, կամ ընդգրկում են ! նշանը, տիպից(շրջանակից) հետո, իրենցից ներկայացնում են կարևոր կամ բեկումնային փոփոխություններ (այն համապատասխանում է Semantic Versioning-ի MAJOR տեսակին)։ BREAKING CHANGE-ը կարող է հանդիսանալ ցանկացած տիպի commit-ի մաս։
  4. fix:-ից և feat:-ից բացի այլ տիպերի օգտագործումը թույլատրվում է, օրինակ՝ @commitlint/config-conventional (հիմնվելով Angular-ի կոնվենցիայի վրա) առաջարկում է build:, chore:, ci:, docs:, style:, refactor:, perf:, test: և այլն:
  5. BREAKING CHANGE: <description> բացի այլ վերջավորություններ կարող են տրամադրվել և հետևել git թրեյլերի ձևաչափ-ին հարակից կոնվենցիաներին։

Լրացուցիչ տիպերը պարտադիր չեն Conventional Commits-ի դասակարգմամբ և չունեն անուղղակի ազդեցություն իմաստային տարբերակման մեջ (եթե դրանք չեն ներառում BREAKING CHANGE): Հանձնարարականի տիպին կարող է տրվել շրջանակ՝ լրացուցիչ համատեքստային ինֆորմացիա տրամադրելու համար։ Այն օգտագործվում է փակագծերի մեջ, հետևյալ կերպ՝ 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 հաղորդագրություն՝ ! նշանով, որպեսզի ուշադրություն գրավենք կատարված կարևոր փոփոխությունների համար

feat!: send an email to the customer when a product is shipped

Commit հաղորդագրություն՝ շրջանակով և ! նշանով, որպեսզի ուշադրություն գրավենք կատարված կարևոր փոփոխությունների համար

feat(api)!: send an email to the customer when a product is shipped

Commit հաղորդագրություն՝ միաժամանակ և՛ ! նշանով, և՛ BREAKING CHANGE վերջավորությունով

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Commit հաղորդագրություն՝ առանց մարմնի

docs: correct spelling of CHANGELOG

Commit հաղորդագրություն՝ շրջանակով

feat(lang): add Polish language

Commit հաղորդագրություն՝ մի քանի պարագրաֆ մարմնով և մի քանի վերջավորություններով

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

Հստակեցում

“MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” բառերն այս փաստաթղթում պետք է մեկնաբանվեն այնպես, ինչպես նկարագրված է RFC 2119-ում։

  1. Commit-ները պետք է ունեն տիպ՝ նախածանցի տեսքով, որը պետք է բաղկացած լինի գոյականից, feat, fix և այլն, որին հաջորդում են ոչ պարտադիր շրջանակը, ոչ պարտադիր !-ը և պարտադիր վերջակետ ու բացատ:
  2. feat տիպը պետք է օգտագործել այն ժամանակ, երբ Ձեր ծրագրում ավելացնում եք նոր հատկանիշներ։
  3. fix տիպը պետք է օգտագործել այն ժամանակ, երբ Ձեր ծրագրում կատարում եք ուղղումներ։
  4. Շրջանակը պետք է նշել տիպից հետո՝ փակագծերի մեջ։ Այն կարող է լինել Ձեր փոփոխած հատվածի վերնագիրը, օրինակ fix(parser):`։
  5. Նկարագիրը պետք է գրված լինի տիպից կամ շրջանակից հետո՝ պահելով դրանց միջև վերջակետ և բացատ։ Այն Ձեր կատարած փոփոխությունների կարճ նկարագիրն է, օրինակ՝ fix: array parsing issue when multiple spaces were contained in string։
  6. Մարմինը կարելի է գրել նկարագրությունից հետո։ Այն Ձեր կատարած փոփոխությունների լայն նկարագիրն է։ Այն պետք է պահի մեկ դատարկ տող՝ նկարագրի միջև։
  7. Commit-ի մարմինը ունի ազատ գրելաձև, կարող է պարունակել տառեր, թվեր, մի քանի պարբերություններ և այլն։
  8. Մեկ կամ ավելի վերջավորությունները պետք է ունենան մեկ դատարկ տող՝ առանձնացվելով մարմնից(ավելին կարող եք կարդալ git trailer convention-ում)։
  9. Վերջավորության նշանը պետք Է օգտագործի -՝ բացատ նիշերի փոխարեն, օրինակ՝ Acked-by (սա օգնում է տարբերակել վերջավորությունը բազմաբնույթ պարբերությունից): Բացառություն է արվում `BREAKING CHANGE-ի համար, որը կարող Է օգտագործվել նաև որպես նշան:
  10. Վերջավորության արժեքը կարող Է պարունակել բացատներ և նոր տողեր, և վերլուծությունը պետք Է ավարտվի, երբ հաջորդ վավեր վերջավորությունը նկատվում է:
  11. Breaking change-երը պետք է նշված լինեն տիպում կամ շրջանակում, և կամ էլ վերջավորության մեջ։
  12. Եթե գոյություն ունի վերջավորություն, ապա breaking change-ը պետք է լինի մեծատառ, օրինակ՝ BREAKING CHANGE: environment variables now take precedence over config files։
  13. Եթե ներառված է տիպի(շրջանակի) նախածանցում, ապա խախտման փոփոխությունները պետք Է նշված լինեն ! :-ից անմիջապես առաջ: Եթե !-ն օգտագործվում է, BREAKING CHANGE-ը կարող է բաց թողնել ստորագիր հատվածից, և պարտավորության նկարագրությունը պետք Է օգտագործվի՝ նկարագրելու փոփոխությունը:
  14. feat և fix տիպերից բացի կարող են օգտագործվել Ձեր commit հաղորդագրություններում, օրինակ՝ docs: updated ref docs.։
  15. Այն ինֆորմացիոն տարրերը, որոնք կազմված են Conventional Commits-ի MUST NOT տեսակից իրականացնողների կողմից դիտարկվում են, որպես գործի զգայուն հատված, բացառությամբ BREAKING CHANGE-ի որը պետք է լինի մեծատառ։
  16. BREAKING-CHANGE MUST-ը BREAKING CHANGE հոմանիշն է, երբ օգտագործվում է, որպես վերջավորություն։

Ինչ՞ու օգտագործել Conventional Commits-ը

Հ․Տ․Հ․

Ինչպե՞ս պետք է վարվեմ commit հաղորդագրությունների հետ նախնական զարգացման փուլում:

Մենք խորհուրդ ենք տալիս շարունակել այնպես, կարծես արդեն թողարկել եք պրոդուկտը: Սովորաբար ինչ-որ մեկը, նույնիսկ եթե դա ձեր գործընկեր ծրագրավորողներն են, օգտագործում է ձեր ծրագրաշարը: Նրանք կցանկանան իմանալ, թե ինչն է շտկված, ինչն է կոտրվում և այլն:

Commit-ների վերնագրի տեսակները մեծատառե՞ն են, թե՞ փոքրատառ:

Ցանկացած միջոց կարող է օգտագործվել, բայց ավելի լավ է հետևողական լինել և օգտագործել դրանցից որևէ մեկը:

Ի՞նչ անել, եթե commit-ը համապատասխանում է commit-ների մեկից ավելի տեսակներին:

Վերադարձեք և հնարավորության դեպքում մի քանի commit-ներ կատարեք: Conventional Commits-ը օգտագործելու իմաստներից մեկը՝ մեր commit հաղորդագրություններն ու PR-ները ավելի կազմակերպված դարձնելն է:

Արդյո՞ք սա չի խանգարում պրոյեկտի արագ զարգացմանը և արագ կրկնմանը:

Այն խանգարում է արագ շարժվել անկազմակերպ կերպով: Այն օգնում է Ձեզ երկարաժամկետ արագ շարժվել բազմաթիվ նախագծերի մեջ՝ տարբեր ներդրողների հետ:

Հնարավո՞ր է, որ Conventional Commits-ը ծրագրավորողներին սահմանափակի իրենց կատարած commit-ների տեսակը, քանի որ նրանք կմտածեն տրամադրված տեսակների վրա:

Conventional Commits-ը մեզ խրախուսում է ավելի շատ կատարել որոշակի տեսակի commit-ներ, ինչպիսիք են ուղղումները: Բացի դրանից, Conventional Commits-ի ճկունությունը թույլ է տալիս Ձեր թիմին գտնել իրենց տեսակները և ժամանակի ընթացքում փոխել դրանք:

Ինչպե՞ս է դա կապված SemVer-ի հետ:

fix տեսակի պարտավորությունները պետք է թարգմանվեն PATCH թողարկումներով: feat տեսակի պարտավորությունները պետք է թարգմանվեն MINOR թողարկումներով: Հանձնարարություններում BREAKING CHANGE ունեցող պարտավորությունները, անկախ տեսակից, պետք է թարգմանվեն MAJOR թողարկումներով:

Ինչպես պետք է տարբերակեմ իմ ընդլայնումները Conventional Commits-ի սպեցիֆիկացիայի համար (օրինակ @jameswomack/conventional-commit-spec):

Մենք խորհուրդ ենք տալիս օգտագործել SemVer-ը, որպեսզի թողարկեք ձեր սեփական ընդլայնումները այս բնութագրին (և խրախուսում ենք ձեզ կատարել այս ընդլայնումները:)

Ի՞նչ անեմ, եթե պատահաբար օգտագործեմ սխալ commit-ի տեսակը:

Երբ դուք օգտագործում եք այնպիսի տեսակ, որը համապատասխանում է բնութագրին, բայց ոչ ճիշտ, օրինակ. fix՝ feat-ի փոխարեն

Նախքան սխալը միաձուլելը կամ բաց թողնելը, մենք խորհուրդ ենք տալիս օգտագործել git rebase -i՝ կատարման պատմությունը խմբագրելու համար: Թողարկումից հետո մաքրումը կտարբերվի՝ կախված ձեր օգտագործած գործիքներից և գործընթացներից:

Երբ դուք օգտագործում եք հատուկ ոչ տեսակ, օրինակ. feet՝ feat-ի փոխարեն

Վատագույն սցենարի դեպքում աշխարհի վերջը չէ, եթե commit-ը վայրէջք կատարի, որը չի համապատասխանում Conventional Commits-ի պահանջներին: Դա պարզապես նշանակում է, որ commit-ը բաց կթողնի այն գործիքները, որոնք հիմնված են բնութագրերի վրա:

Արդյո՞ք իմ բոլոր մասնակիցները պետք է օգտագործեն Conventional Commits-ի հստակեցումը:

Ո՛չ։ Եթե դուք օգտագործում եք squash-ի վրա հիմնված աշխատանքային հոսք Git-ի առաջատար սպասարկիչները կարող են մաքրել commit հաղորդագրությունները, քանի որ դրանք միաձուլվում են՝ առանց աշխատանքային ծանրաբեռնվածության ավելացման պատահական commiter-ին: Սրա համար ընդհանուր աշխատանքային հոսքն այն է, որ ձեր git համակարգը ինքնաբերաբար PR-ը կմիաձուլի մեկ squash commit-ի մեջ, որպեսզի առաջատար սպասարկիչը մուտքագրի համապատասխան git commit հաղորդագրությունը միաձուլման համար:

Ինչպե՞ս են Conventional Commits-ը վերաբերվում վերադարձի(revert) commit-ներին:

Կոդը վերադարձնելը կարող է բարդ լինել. դուք վերադարձնու՞մ եք մի քանի commit-ներ: եթե վերադարձնեք որևէ հատկանիշ(feature), հաջորդ թողարկումը դրա փոխարեն կարկատա՞կ պետք է լինի:

Conventional Commits-ը բացահայտ ջանքեր չի գործադրում հետադարձ վարքագիծը սահմանելու համար: Փոխարենը թողնում ենք հեղինակներին օգտագործել types-ի և footers-ի ճկունությունը՝ զարգացնելու իրենց տրամաբանությունը հետադարձումների հետ աշխատելու համար:

Առաջարկություններից մեկն է օգտագործել revert տիպը և վերջավորություն, որը հղում է կատարում վերադարձվող SHA-ներին՝

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868