සම්මුතිවාදී කමිට්ස් (Conventional Commits) 1.0.0

සාරාංශය

සම්මුතිවාදී කමිට් (Conventional Commits) පිරිවිතරය යනු කමිට් පණිවිඩ (commit messages) සඳහා වන සැහැල්ලු සම්මුතියකි. එය පැහැදිලි කමිට් ඉතිහාසයක් (commit history) නිර්මාණය කිරීම සඳහා සරල නීති මාලාවක් සපයයි; එමඟින් ස්වයංක්‍රීය මෙවලම් (automated tools) නිර්මාණය කිරීම පහසු කරයි. මෙම සම්මුතිය SemVer සමඟ මනාව ගැලපෙන අතර, කමිට් පණිවිඩ මගින් සිදු කරන ලද විශේෂාංග (features), නිවැරදි කිරීම් (fixes) සහ බිඳවැටීම් වෙනස්කම් (breaking changes) විස්තර කරයි.

කමිට් පණිවිඩය පහත පරිදි ව්‍යුහගත කළ යුතුය:

<වර්ගය>[විකල්ප විෂය පථය]: <විස්තරය>

[විකල්ප ප්‍රධාන කොටස]

[විකල්ප පාදකය(න්)]

ඔබේ මෘදුකාංග පුස්තකාලය භාවිතා කරන්නන්ට අදහස සන්නිවේදනය කිරීම සඳහා කමිට් පණිවිඩය පහත සඳහන් ව්‍යුහාත්මක අංග අඩංගු විය යුතුය:

1. fix: ‘fix’ වර්ගයේ කමිට් එකක් මගින් ඔබේ කේත පද්ධතියේ පවතින දෝෂයක් නිවැරදි කිරීමක් පෙන්නුම් කරයි (මෙය Semantic Versioning හි ‘PATCH’ සමඟ සම්බන්ධ වේ).
2. feat: ‘feat’ වර්ගයේ කමිට් එකක් මගින් කේත පද්ධතියට නව විශේෂාංගයක් හඳුන්වා දීම පෙන්නුම් කරයි (මෙය Semantic Versioning හි ‘MINOR’ සමඟ සම්බන්ධ වේ).
3. BREAKING CHANGE: පාදකයේ (footer) BREAKING CHANGE: ලෙස සඳහන් වන, හෝ වර්ගය/විෂය පථය අවසානයේ ! ලකුණ ඇතුළත් වන කමිට් එකක් මගින් මෘදුකාංගයේ අතුරුමුහුණතේ (API) බිඳවැටීමක් හෙවත් විශාල වෙනසක් පෙන්නුම් කරයි (මෙය Semantic Versioning හි ‘MAJOR’ සමඟ සම්බන්ධ වේ). ඕනෑම වර්ගයක කමිට් එකක BREAKING CHANGE එකක් අඩංගු විය හැක.
4. fix: සහ feat: හැර වෙනත් වර්ග සඳහාද අවසර ඇත, උදාහරණයක් ලෙස @commitlint/config-conventional (Angular සම්මුතිය මත පදනම් වූ) විසින් build:, chore:, ci:, docs:, style:, refactor:, perf:, test:, සහ අනෙකුත් වර්ග නිර්දේශ කරයි.
5. BREAKING CHANGE: <විස්තරය> හැර වෙනත් පාදකයන් (footers) ද සැපයිය හැකි අතර ඒවා git trailer ආකෘතියට සමාන සම්මුතියක් අනුගමනය කරයි.

අතිරේක වර්ග සම්මුතිවාදී කමිට් පිරිවිතරය මගින් අනිවාර්ය නොකරන අතර, ඒවා Semantic Versioning කෙරෙහි ව්‍යංග බලපෑමක් ඇති නොකරයි (BREAKING CHANGE එකක් ඇතුළත් නොවේ නම්).

කමිට් වර්ගයකට අමතර සන්දර්භීය තොරතුරු සැපයීම සඳහා වරහන් තුළ විෂය පථයක් (scope) ඇතුළත් කළ හැකිය, උදා: feat(parser): add ability to parse arrays.

උදාහරණ

විස්තරය සහ 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

බිඳවැටීමක් (breaking change) පිළිබඳ අවධානය යොමු කිරීමට ! සහිත කමිට් පණිවිඩය

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

විෂය පථය (scope) සහ ! සහිත කමිට් පණිවිඩය

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

! සහ BREAKING CHANGE පාදකය යන දෙකම සහිත කමිට් පණිවිඩය

chore!: drop support for Node 6

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

ප්‍රධාන කොටසක් (body) නොමැති කමිට් පණිවිඩය

docs: correct spelling of CHANGELOG

විෂය පථය සහිත කමිට් පණිවිඩය

feat(lang): add Sinhala language

ඡේද කිහිපයකින් යුත් ප්‍රධාන කොටස සහ පාදකයන් කිහිපයක් සහිත කමිට් පණිවිඩය

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

පිරිවිතරය (Specification)

මෙම ලේඛනයේ ඇති “සිදු කළ යුතුය” (MUST), “සිදු නොකළ යුතුය” (MUST NOT), “අවශ්‍ය වේ” (REQUIRED), “කළ යුතුය” (SHALL), “නොකළ යුතුය” (SHALL NOT), “කළ යුත්තේය” (SHOULD), “නොකළ යුත්තේය” (SHOULD NOT), “නිර්දේශිතයි” (RECOMMENDED), “හැකිය” (MAY), සහ “විකල්ප වේ” (OPTIONAL) යන වචන RFC 2119 හි විස්තර කර ඇති පරිදි අර්ථකථනය කළ යුතුය.

1. කමිට් සඳහා වර්ගයක් (type) උපසර්ගයක් ලෙස තිබිය යුතුය. එය නාම පදයක් විය යුතුය (feat, fix, ආදී), ඉන්පසුව විකල්ප විෂය පථයක් (scope), විකල්ප ! ලකුණක් සහ අනිවාර්යයෙන් තිතක් (colon) සහ හිස්තැනක් (space) තිබිය යුතුය.
2. ඔබේ යෙදුමට හෝ පුස්තකාලයට නව විශේෂාංගයක් එක් කරන විට feat වර්ගය භාවිතා කළ යුතුය.
3. ඔබේ යෙදුමේ පවතින දෝෂයක් නිවැරදි කරන විට fix වර්ගය භාවිතා කළ යුතුය.
4. වර්ගයකට පසුව විෂය පථයක් (scope) සැපයිය හැකිය. විෂය පථයක් යනු කේත පද්ධතියේ නිශ්චිත කොටසක් විස්තර කරන නාම පදයක් විය යුතු අතර එය වරහන් වලින් වට විය යුතුය, උදා: fix(parser):
5. වර්ගය/විෂය පථය උපසර්ගයට පසුව ඇති තිත සහ හිස්තැනට පසුව විස්තරයක් (description) අනිවාර්යයෙන්ම තිබිය යුතුය. විස්තරය යනු කේත වෙනස්කම් පිළිබඳ කෙටි සාරාංශයකි, උදා: fix: array parsing issue when multiple spaces were contained in string.
6. කෙටි විස්තරයට පසුව, කේත වෙනස්කම් පිළිබඳ අමතර තොරතුරු සැපයීම සඳහා දිගු කමිට් ප්‍රධාන කොටසක් (body) සැපයිය හැකිය. ප්‍රධාන කොටස විස්තරයට පසුව එක් හිස් පේළියකින් පසුව ආරම්භ විය යුතුය.
7. කමිට් ප්‍රධාන කොටස ඕනෑම ආකාරයක විය හැකි අතර නව පේළි වලින් වෙන් කරන ලද ඡේද ගණනාවකින් සමන්විත විය හැකිය.
8. ප්‍රධාන කොටසට පසුව එක් හිස් පේළියකින් පසුව පාදක (footers) එකක් හෝ කිහිපයක් සැපයිය හැකිය. සෑම පාදකයක්ම වචන ටෝකනයකින් සමන්විත විය යුතු අතර, ඉන් පසුව :<space> හෝ <space># බෙදුම්කාරකය සහ පසුව අගයක් තිබිය යුතුය (මෙය git trailer සම්මුතියෙන් ආභාසය ලබා ඇත).
9. පාදකයක ටෝකනය සඳහා හිස්තැන් වෙනුවට - භාවිතා කළ යුතුය, උදා: Acked-by (මෙය බහු-ඡේද ප්‍රධාන කොටසකින් පාදක කොටස වෙන්කර හඳුනා ගැනීමට උපකාරී වේ). BREAKING CHANGE සඳහා මෙහිදී ව්‍යතිරේකයක් පවතී, එය ටෝකනයක් ලෙසද භාවිතා කළ හැක.
10. පාදකයක අගයෙහි හිස්තැන් සහ නව පේළි තිබිය හැකි අතර, මීළඟ නිවැරදි පාදක ටෝකනය/බෙදුම්කාරක යුගලය හමු වූ විට විග්‍රහ කිරීම (parsing) අවසන් විය යුතුය.
11. බිඳවැටීම් වෙනස්කම් (Breaking changes) කමිට් එකක වර්ගය/විෂය පථය උපසර්ගයෙහි හෝ පාදකයේ ඇතුළත් කළ යුතුය.
12. පාදකයක ඇතුළත් කරන්නේ නම්, බිඳවැටීම් වෙනස්කම BREAKING CHANGE යන ලොකු අකුරු සහිත පෙළින් ආරම්භ විය යුතු අතර, ඉන් පසුව තිතක්, හිස්තැනක් සහ විස්තරයක් තිබිය යුතුය. උදා: BREAKING CHANGE: environment variables now take precedence over config files.
13. වර්ගය/විෂය පථය උපසර්ගයෙහි ඇතුළත් කරන්නේ නම්, බිඳවැටීම් වෙනස්කම් : ට පෙර වහාම ! ලකුණින් දැක්විය යුතුය. ! භාවිතා කරන්නේ නම්, පාදක කොටසින් BREAKING CHANGE: මඟ හැරිය හැකි අතර, බිඳවැටීම විස්තර කිරීමට කමිට් විස්තරය භාවිතා කළ යුතුය.
14. ඔබේ කමිට් පණිවිඩවල feat සහ fix හැර වෙනත් වර්ග ද භාවිතා කළ හැකිය, උදා: docs: update ref docs.
15. සම්මුතිවාදී කමිට් වල අඩංගු තොරතුරු ඒකක, ක්‍රියාත්මක කරන්නන් විසින් අකුරු ප්‍රමාණය (case sensitive) සලකා නොබැලිය යුතුය, නමුත් BREAKING CHANGE සෑම විටම ලොකු අකුරින් තිබිය යුතුය.
16. පාදකයක ටෝකනයක් ලෙස භාවිතා කරන විට BREAKING-CHANGE යන්න BREAKING CHANGE සඳහා සමාන පදයක් විය යුතුය.

සම්මුතිවාදී කමිට්ස් භාවිතා කරන්නේ ඇයි?

• CHANGELOG ස්වයංක්‍රීයව ජනනය කිරීම සඳහා.
• කමිට් වර්ග මත පදනම්ව Semantic Version (SemVer) අගය වැඩි කිරීම (bump) ස්වයංක්‍රීයව තීරණය කිරීම සඳහා.
• කණ්ඩායම් සාමාජිකයින්ට, පොදු ජනයාට සහ අනෙකුත් පාර්ශවකරුවන්ට වෙනස්කම්වල ස්වභාවය සන්නිවේදනය කිරීම සඳහා.
• Build සහ publish ක්‍රියාවලීන් ක්‍රියාත්මක කිරීම සඳහා.
• ව්‍යුහගත කමිට් ඉතිහාසයක් මඟින් මිනිසුන්ට ඔබේ ව්‍යාපෘති සඳහා දායක වීම පහසු කිරීම සඳහා.

නිතර අසනු ලබන ප්‍රශ්න (FAQ)

ආරම්භක සංවර්ධන අවධියේදී (initial development phase) මම කමිට් පණිවිඩ හැසිරවිය යුත්තේ කෙසේද?

ඔබ දැනටමත් නිෂ්පාදනය නිකුත් කර ඇති පරිදි කටයුතු කරන ලෙස අපි නිර්දේශ කරමු. සාමාන්‍යයෙන් කවුරුන් හෝ (ඔබේ සම-සංවර්ධකයින් වුවද) ඔබේ මෘදුකාංගය භාවිතා කරයි. ඔවුන්ට මොනවාද නිවැරදි කර ඇත්තේ, මොනවාද බිඳී ඇත්තේ යන්න දැන ගැනීමට අවශ්‍ය වනු ඇත.

කමිට් මාතෘකාවේ වර්ග ලොකු අකුරින්ද නැත්නම් කුඩා අකුරින්ද තිබිය යුතුද?

ඕනෑම ආකාරයක් භාවිතා කළ හැක, නමුත් ස්ථාවරව (consistent) එකම ආකාරයක් භාවිතා කිරීම වඩාත් සුදුසුය.

කමිට් එක වර්ග එකකට වඩා වැඩි ගණනකට ගැලපේ නම් මා කුමක් කළ යුතුද?

හැකි සෑම විටම ආපසු ගොස් කමිට් කිහිපයක් සාදන්න. සම්මුතිවාදී කමිට් වල එක් ප්‍රයෝජනයක් වන්නේ වඩාත් සංවිධානාත්මක කමිට් සහ PR නිර්මාණය කිරීමට අපව යොමු කිරීමයි.

මෙය වේගවත් සංවර්ධනයට සහ වේගවත් පුනරාවර්තනයට බාධාවක් නොවේද?

එය අසංවිධානාත්මක ලෙස වේගයෙන් ගමන් කිරීම අධෛර්යමත් කරයි. විවිධ දායකයින් සිටින ව්‍යාපෘති කිහිපයක දිගුකාලීනව වේගයෙන් ගමන් කිරීමට මෙය ඔබට උපකාරී වේ.

ලබා දී ඇති වර්ග ගැන සිතීම නිසා සංවර්ධකයින් කරන කමිට් වර්ග සීමා වීමට සම්මුතිවාදී කමිට්ස් හේතු විය හැකිද?

සම්මුතිවාදී කමිට්ස් මඟින් ‘fixes’ වැනි ඇතැම් වර්ගවල කමිට් වැඩිපුර කිරීමට අපව දිරිමත් කරයි. එය හැරුණු විට, සම්මුතිවාදී කමිට් වල නම්‍යශීලීභාවය නිසා ඔබේ කණ්ඩායමට තමන්ගේම වර්ග නිර්මාණය කිරීමට සහ කාලයත් සමඟ ඒවා වෙනස් කිරීමට ඉඩ සලසයි.

මෙය SemVer සමඟ සම්බන්ධ වන්නේ කෙසේද?

• fix වර්ගයේ කමිට් PATCH නිකුත් කිරීම් ලෙස පරිවර්තනය කළ යුතුය.
• feat වර්ගයේ කමිට් MINOR නිකුත් කිරීම් ලෙස පරිවර්තනය කළ යුතුය.
• කමිට් වර්ගය කුමක් වුවත් BREAKING CHANGE සහිත කමිට් MAJOR නිකුත් කිරීම් ලෙස පරිවර්තනය කළ යුතුය.

සම්මුතිවාදී කමිට් පිරිවිතරයට මා කරන දිගු කිරීම් (extensions) සඳහා අනුවාද (versioning) ලබා දිය යුත්තේ කෙසේද? උදා: @jameswomack/conventional-commit-spec

ඔබේම දිගු කිරීම් නිකුත් කිරීම සඳහා SemVer භාවිතා කරන ලෙස අපි නිර්දේශ කරමු (තවද මෙම දිගු කිරීම් කිරීමට අපි ඔබව දිරිමත් කරමු!).

මම අහම්බෙන් වැරදි කමිට් වර්ගයක් භාවිතා කළහොත් මා කුමක් කළ යුතුද?

පිරිවිතරයේ පවතින නමුත් වැරදි වර්ගයක් භාවිතා කළ විට (උදා: feat වෙනුවට fix)

එම වැරැද්ද ඒකාබද්ධ කිරීමට (merge) හෝ නිකුත් කිරීමට පෙර, කමිට් ඉතිහාසය සංස්කරණය කිරීමට git rebase -i භාවිතා කරන ලෙස අපි නිර්දේශ කරමු. නිකුත් කිරීමෙන් පසුව, ඔබ භාවිතා කරන මෙවලම් සහ ක්‍රියාවලීන් අනුව පිරිසිදු කිරීම වෙනස් වනු ඇත.

පිරිවිතරයේ නොමැති වර්ගයක් භාවිතා කළ විට (උදා: feat වෙනුවට feet)

නරකම අවස්ථාවක, සම්මුතිවාදී කමිට් පිරිවිතරයට නොගැලපෙන කමිට් එකක් ඇතුළත් වීම ලෝක අවසානය නොවේ. එයින් අදහස් වන්නේ එම කමිට් එක පිරිවිතරය මත පදනම් වූ මෙවලම් වලට මඟ හැරෙනු ඇති බවයි.

මගේ සියලුම දායකයින් (contributors) සම්මුතිවාදී කමිට් පිරිවිතරය භාවිතා කළ යුතුද?

නැත! ඔබ Git හි squash මත පදනම් වූ කාර්ය ප්‍රවාහයක් භාවිතා කරන්නේ නම්, ප්‍රධාන නඩත්තු කරන්නන්ට (maintainers) කමිට් ඒකාබද්ධ කිරීමේදී පණිවිඩ පිරිසිදු කළ හැකිය—එමඟින් සාමාන්‍ය දායකයින්ට අමතර වැඩ කොටසක් එක් නොවේ. මෙහි පොදු කාර්ය ප්‍රවාහයක් වන්නේ pull request එකකින් එන කමිට් ස්වයංක්‍රීයව squash කිරීමට සැලැස්වීම සහ නඩත්තු කරන්නාට නිසි කමිට් පණිවිඩය ඇතුළත් කිරීමට පෝරමයක් ලබා දීමයි.

සම්මුතිවාදී කමිට්ස් ‘revert’ කමිට් හසුරුවන්නේ කෙසේද?

කේතය පෙර තත්වයට පත් කිරීම (Reverting) සංකීර්ණ විය හැකිය: ඔබ කමිට් කිහිපයක් පෙර තත්වයට පත් කරනවාද? ඔබ විශේෂාංගයක් පෙර තත්වයට පත් කරන්නේ නම්, ඊළඟ නිකුතුව patch එකක් විය යුතුද?

සම්මුතිවාදී කමිට්ස් මඟින් revert හැසිරීම අර්ථ දැක්වීමට නිශ්චිත උත්සාහයක් නොගනී. ඒ වෙනුවට, revert හැසිරවීම සඳහා ඔවුන්ගේම තර්කනය වර්ධනය කර ගැනීමට වර්ග සහ පාදකවල නම්‍යශීලීභාවය භාවිතා කිරීමට මෙවලම් කතුවරුන්ට අපි ඉඩ දෙමු.

එක් නිර්දේශයක් වන්නේ revert වර්ගය සහ පෙර තත්වයට පත් කරන කමිට් වල SHA අගයන් සඳහන් කරන පාදකයක් භාවිතා කිරීමයි:

revert: let us never again speak of the noodle incident

Refs: 676104e, a215868