ترجمه شده از اینجا با زبان خودمونی تر که هر آدمی بفهمه (هم منی که چند ساله کار میکنم هم اونی که تازه شروع کرده)
این که شما بخواهید در یک پروژه متن باز مشارکت داشته باشید یا اینکه یک پروژه رو با دوستانتون پیش ببرید، نیازمند یک فرمت یا قانون مشخص برای کامیت زدنه! زمانی این نیاز احساس میشه که کامیت های پروژه زیاد شدن و شما نمیدونید دقیقا توی کدوم کامیت چیکار کردید. درست کامیت زدن باعث میشه تا بتونید راحت تر تغییرات رو مدیریت و در انتها یک ریپوزیتوری خوب بسازید که همه بتونن بفهمن شما دقیقا چیکار کردید و بتونن بهتر کمک کنند !
ببین چطوری میتونی با تغییر دادن مدل کامیت زدنت، بین خودت و بقیه تفاوت ایجاد کنی. نمونه ها
به شخصه استفاده از این قرارداد یا انواع دیگه ای از اینجور قرارداد ها برای کامیت زدن رو پیشنهاد میکنم. چرا که نه تنها به درد کار های شخصی و تیمی کوچیک میخوره، بلکه به درد کار های بزرگ و سازمانی هم میخورن! باعث میشه از یه جایی به بعد کار ها هم سریع تر پیش برن، هم دقیق تر و هم با بازدهی بیشر ! خلاصه که هرچی بگم از اینجور قرارداد ها (حالا چه برای کامیت چه برای مثلا گذاشتن اسم متغیر) کم گفتم !
Tip
یه نگاهی به این CLI و لاگ (گزارش) تغییراتش بندازید تا تضمینی برای کاربردی بودن این قرارداد داشته باشید! git-conventional-commits
این بخش رو خودم اضافه میکنم. ببینید ما از این فرمت زیر استفاده میکنیم تا کامیت هامون خوانا تر بشه و راحت تر بتونیم بفهمیم چیکار کردیم. خیلی از پروژه های بزرگ اوپن سورس دنیا مثل انگیولار اینحوری کامیت میزنن. این فقط یه قرارداد یا قائده هست که بهتره استفادش کنیم. اول تایپ کامیت رو میاریم، بعد (این بخش اختیاریه) میتونیم بگیم که این کامیت کجا رو مشخصا تغییر داده و بعد باید یه توضیح کوچیک بدیم. بعد باید تتوضیحات جامع تر ارائه کنیم و در نهایت باید یه فوتر ارائه کنیم. جلو ر قشنگ توضیح میدم که اینا دقیقا یعنی چی. فقط اینا رو نوشتم که فرمت پایین رو متوجه بشین !
<type>(<optional scope>): <subject> empty separator line <optional body> empty separator line <optional footer>
Merge branch '<branch name>'
Follows default git merge message
- تغییرات مربوط به API برنامه (منظور روش استفاده از کد هاتون و خود کد هاتونه نه Web API)
- تایپ
featبرای کامیت هایی که یه ویژگی جدید رو به کد هاتون اضافه میکنن - تایپ
fixبرای کامیت هایی که یک باگ توی پروژه رو فیکس میکنن
- تایپ
- تایپ
refactorبرای کامیت هایی که ساختار بندی کد ررو تغییر دادین یا یه بخشی رو باز نویسی کردین ولی در مجموع تغییری تو خروجی نرم فازار نداره- تایپ
perfاین حالت خاص همونrefactorهست بطوریکه اگه اون تغییرات رو جوری داده باشید که روی پرفورمنس اثر مستقیم گذاشته باشه، از این استفاده میکنید!
- تایپ
- تایپ
styleبرای کامیت هایی که میزنیشون ولی تاثیری روی کد ندارن (مثلا فرمت کردن کد و پاک کردن spaceهای اضافه ای که زدی و...) - تایپ
testبرای کامیت هایی که تست هایی که یادت رفته اضافه کنی رو اضافه میکنن یا تست های قبلی تصحیح میکنن - تایپ
docsبرای کامیت هایی که فقط روی داکیومنت کد تاثیر دارن - تایپ
buildبرای کامیت هایی که روی اجزای بیلدت تاثیر میزان مثلا Dependency های پروژت رو تغییر میدن یا ورژن پروژه رو تغییر میدن - تایپ
opsبرای کامیت هایی که روی بخش های اجرایی پروژه مثل زیرساخت ها ، گسترش و پیاده سازی ،بازیابی و بکاپ و ریکاوری و... تاثیر دارن - تایپ
choreبرای کامیت های متفرقه، مثلا ادیت کردن فایل.gitignore
در واقع scope یه سری اطلاعات در مورد اینکه تغییرات کجا اتفاق افتاده رو ارائه می کنن
- یک بخش کاملا اختیاری هست
- اسکوپ ها به پروژه بستگی دارن (یک وقت یه اسکوپ یشه یه پروشه، یه وقتی یه اسکوپ میشه یک فایل)
- هیچوقت اینجا نگین دقیقا مربوط به کدوم مسئله (مشکل یا باگ یا هرچی) میشه این کامیت
درواقع subject ها یه توضیح مختصر و مفید از تغییرات توی کامیت ارائه میکنند
- این یک بخش اجباری از این فرمت هست
- از فعل امری و زمان حال استفاده کنید، مثل "change" نه "changed" یا نه "changes"
- مثلا اینجوری وسط کامیت داستان تعریف نکنین
This commit will <subject>
- مثلا اینجوری وسط کامیت داستان تعریف نکنین
- حرف اول رو کپتال (بزرگ) ننویسین
- آخرش از نقطه (.) استفاده نکنین
در واقع body همون دلیل یا انگیزۀ ای که باعث ایجاد این تغییرات شدهست
- این یک بخش اختیاری از این فرمت کامیت زدن است
- از فعل امری و زمان حال استفاده کنید، مثل "change" نه "changed" یا نه "changes"
- اینجا میتونین بگید این کامیت مربوط که کدوم مسئله میشه (آقا مثلا یه نیازی بود یا یه باگی بوده حلش کردین اینجا میتونین بگین کدوم نیاز یا کدوم مشکل و باگ)
در واقع footer باید شامل همه اطلاعات در مورد Breaking Changes(تغییراتی که ساختار ها و قابلیت های قبلی رو کنار گذاشتن) و همچنین یه جای خوب برای رفرنس زدن به مسئله مطرح شده در گیت هاب در انتهای کامیت است.
- این یک بخش اختیاری از این فرمت کامیت زدن هست
- بطور اختیاری رفرنس به issue میتونه همراه با آیدی اون issue باشه.
- و اینکه Breaking Changes باید با کلمه
BREAKING CHANGES:به همراه یک space یا دوتا خط جدید شروع بشوند و بعد از این، بقیه پیام کامیت باید مربوط به همین Breaking Changes باشد
-
feat(shopping cart): add the amazing button -
feat: remove ticket list endpoint refers to JIRA-1337 BREAKING CHANGES: ticket enpoints no longer supports list all entites. -
fix: add missing parameter to service call The error occurred because of <reasons>. -
build(release): bump version to 1.0.0 -
build: update dependencies -
refactor: implement calculation method as recursion -
style: remove empty line
اسکریپت های گیت (Git Hook Scripts) برای اطمینان از اینکه فرمت هدر کامیت را صحبح وارد میکنید (هدر کامیت همان تایپ و اسکوپ و سابجکت هست)
-
فایل زیر رو در مسیر
.git-hooks/commit-msgبسازید#!/usr/bin/env sh commit_message="$1" # exit with a non zero exit code incase of an invalid commit message # use git-conventional-commits, see https://github.com/qoomon/git-conventional-commits git-conventional-commits commit-msg-hook "$commit_message" # or verify $commit_message with your own tooling # ...
-
⚠ فایل
.git-hooks/commit-msgرو قابل اجرا کنید (سیستم های یونیکسی :chmod +x '.git-hooks/commit-msg') -
با دستور مقابل ، پوشه git hook ها رو به
.githooksتغییر دهید :git config core.hooksPath '.git-hooks' -
اگر میخواهید این را با بقیه تیم خود به اشتراک بگذارید، پوشه
.git-hooksرا کامیت کنید. اون ها هم کافیه تا کامتgit confogرو یک بار بعد از کلون کردن ریپوزیتوری صدا بزنن
-
فایل زیر رو در پوشه ریپوزیتوری بسازید
.git/hooks/pre-receive#!/usr/bin/env sh # Pre-receive hook that will block commits with messges that do not follow regex rule commit_msg_type_regex='feat|fix|refactor|style|test|docs|build' commit_msg_scope_regex='.{1,20}' commit_msg_subject_regex='.{1,100}' commit_msg_regex="^(${commit_msg_type_regex})(\(${commit_msg_scope_regex}\))?: (${commit_msg_subject_regex})\$" merge_msg_regex="^Merge branch '.+'\$" zero_commit="0000000000000000000000000000000000000000" # Do not traverse over commits that are already in the repository excludeExisting="--not --all" error="" while read oldrev newrev refname; do # branch or tag get deleted if [ "$newrev" = "$zero_commit" ]; then continue fi # Check for new branch or tag if [ "$oldrev" = "$zero_commit" ]; then rev_span=`git rev-list $newrev $excludeExisting` else rev_span=`git rev-list $oldrev..$newrev $excludeExisting` fi for commit in $rev_span; do commit_msg_header=$(git show -s --format=%s $commit) if ! [[ "$commit_msg_header" =~ (${commit_msg_regex})|(${merge_msg_regex}) ]]; then echo "$commit" >&2 echo "ERROR: Invalid commit message format" >&2 echo "$commit_msg_header" >&2 error="true" fi done done if [ -n "$error" ]; then exit 1 fi
-
⚠ فایل
.git/hooks/pre-receiveرا قابل اجرا کنید (سیستم های یونیکسی :chmod +x '.git/hooks/pre-receive')
- https://www.conventionalcommits.org/
- https://github.com/angular/angular/blob/master/CONTRIBUTING.md
- http://karma-runner.github.io/1.0/dev/git-commit-msg.html
- https://github.com/github/platform-samples/tree/master/pre-receive-hooks
- https://git.521000.bestmunity/t5/GitHub-Enterprise-Best-Practices/Using-pre-receive-hooks-in-GitHub-Enterprise/ba-p/13863
نیاز دیدم یه ترجمه فارسی از این فایل داشته باشیم
سعی میکنم با هر آپدیتش آپدیت کنم
اگر غلط املایی دیدین تو کامنتا بگید درست میکنم (تقصیر کیبوردمه 😉)
چقدر خوب و کامل بود. ممنون