AmirMahdyJebreily/conventional_commit_messages.md

## conventional_commit_messages.md

      
    Raw
  

              conventional_commit_messages.md
            
          
    کامیت های مرسوم گیت | Conventional Commit Messages

ترجمه شده از اینجا با زبان خودمونی تر که هر آدمی بفهمه (هم منی که چند ساله کار میکنم هم اونی که تازه شروع کرده)

چرا باید خوب کامیت بزنیم ؟

این که شما بخواهید در یک پروژه متن باز مشارکت داشته باشید یا اینکه یک پروژه رو با دوستانتون پیش ببرید، نیازمند یک فرمت یا قانون مشخص برای کامیت زدنه! زمانی این نیاز احساس میشه که کامیت های پروژه زیاد شدن و شما نمیدونید دقیقا توی کدوم کامیت چیکار کردید. درست کامیت زدن باعث میشه تا بتونید راحت تر تغییرات رو مدیریت و در انتها یک ریپوزیتوری خوب بسازید که همه بتونن بفهمن شما دقیقا چیکار کردید و بتونن بهتر کمک کنند !

ببین چطوری میتونی با تغییر دادن مدل کامیت زدنت، بین خودت و بقیه تفاوت ایجاد کنی. نمونه ها
به شخصه استفاده از این قرارداد یا انواع دیگه ای از اینجور قرارداد ها برای کامیت زدن رو پیشنهاد میکنم. چرا که نه تنها به درد کار های شخصی و تیمی کوچیک میخوره، بلکه به درد کار های بزرگ و سازمانی هم میخورن! باعث میشه از یه جایی به بعد کار ها هم سریع تر پیش برن، هم دقیق تر و هم با بازدهی بیشر ! خلاصه که هرچی بگم از اینجور قرارداد ها (حالا چه برای کامیت چه برای مثلا گذاشتن اسم متغیر) کم گفتم !
Tip
یه نگاهی به این CLI و لاگ (گزارش) تغییراتش بندازید تا تضمینی برای کاربردی بودن این قرارداد داشته باشید!  git-conventional-commits


فرمت کامیت زدن

بطور پیشفرض (همه کامیت ها)

این بخش رو خودم اضافه میکنم. ببینید ما از این فرمت زیر استفاده میکنیم تا کامیت هامون خوانا تر بشه و راحت تر بتونیم بفهمیم چیکار کردیم. خیلی از پروژه های بزرگ اوپن سورس دنیا مثل انگیولار اینحوری کامیت میزنن. این فقط یه قرارداد یا قائده هست که بهتره استفادش کنیم. اول تایپ کامیت رو میاریم، بعد (این بخش اختیاریه) میتونیم بگیم که این کامیت کجا رو مشخصا تغییر داده و بعد باید یه توضیح کوچیک بدیم. بعد باید تتوضیحات جامع تر ارائه کنیم و در نهایت باید یه فوتر ارائه کنیم. جلو ر قشنگ توضیح میدم که اینا دقیقا یعنی چی. فقط اینا رو نوشتم که فرمت پایین رو متوجه بشین !
<type>(<optional scope>): <subject>
_{empty separator line}
<optional body>
_{empty separator line}
<optional footer>

صرفا برای Merge کردن از فرمت زیر استفاده کن

Merge branch '<branch name>'

^{Follows default git merge message}
تایپ ها <type>


تغییرات مربوط به API برنامه (منظور روش استفاده از کد هاتون و خود کد هاتونه نه Web API)

تایپ feat برای کامیت هایی که یه ویژگی جدید رو به کد هاتون اضافه میکنن
تایپ fix برای کامیت هایی که یک باگ توی پروژه رو فیکس میکنن


تایپ refactor برای کامیت هایی که ساختار بندی کد ررو تغییر دادین یا یه بخشی رو باز نویسی کردین ولی در مجموع تغییری تو خروجی نرم فازار نداره

تایپ perf این حالت خاص همون refactor هست بطوریکه اگه اون تغییرات رو جوری داده باشید که روی پرفورمنس اثر مستقیم گذاشته باشه، از این استفاده میکنید!


تایپ style برای کامیت هایی که میزنیشون ولی تاثیری روی کد ندارن (مثلا فرمت کردن کد و پاک کردن spaceهای اضافه ای که زدی و...)
تایپ test برای کامیت هایی که تست هایی که یادت رفته اضافه کنی رو اضافه میکنن یا تست های قبلی تصحیح میکنن
تایپ docs برای کامیت هایی که فقط روی داکیومنت کد تاثیر دارن
تایپ build برای کامیت هایی که روی اجزای بیلدت تاثیر میزان مثلا Dependency های پروژت رو تغییر میدن یا ورژن پروژه رو تغییر میدن
تایپ ops برای کامیت هایی که روی بخش های اجرایی پروژه مثل زیرساخت ها ، گسترش و پیاده سازی ،بازیابی و بکاپ و ریکاوری و... تاثیر دارن
تایپ chore برای کامیت های متفرقه، مثلا ادیت کردن فایل .gitignore

محدوده ها (اسکوپ ها) <scope>

در واقع scope یه سری اطلاعات در مورد اینکه تغییرات کجا اتفاق افتاده رو ارائه می کنن

یک بخش کاملا اختیاری هست
اسکوپ ها به پروژه بستگی دارن (یک وقت یه اسکوپ یشه یه پروشه، یه وقتی یه اسکوپ میشه یک فایل)
هیچوقت اینجا نگین دقیقا مربوط به کدوم مسئله (مشکل یا باگ یا هرچی) میشه این کامیت

موضوع <subject>

درواقع  subject ها یه توضیح مختصر و مفید از تغییرات توی کامیت ارائه میکنند

این یک بخش اجباری از این فرمت هست
از فعل امری و زمان حال استفاده کنید، مثل "change" نه "changed" یا نه "changes"

مثلا اینجوری وسط کامیت داستان تعریف نکنین This commit will <subject>


حرف اول رو کپتال (بزرگ) ننویسین
آخرش از نقطه (.) استفاده نکنین

بدنه <body>

در واقع body همون دلیل یا انگیزۀ ای که باعث ایجاد این تغییرات شدهست

این یک بخش اختیاری از این فرمت کامیت زدن است
از فعل امری و زمان حال استفاده کنید، مثل "change" نه "changed" یا نه "changes"
اینجا میتونین بگید این کامیت مربوط که کدوم مسئله میشه (آقا مثلا یه نیازی بود یا یه باگی بوده حلش کردین اینجا میتونین بگین کدوم نیاز یا کدوم مشکل و باگ)

فوتر footer

در واقع 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) برای اطمینان از اینکه فرمت هدر کامیت را صحبح وارد میکنید (هدر کامیت همان تایپ و اسکوپ و سابجکت هست)

اسکریپت commit-msg (برای ریپوزیتوری های لوکال)


فایل زیر رو در مسیر.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 رو یک بار بعد از کلون کردن ریپوزیتوری صدا بزنن


اسکریپت pre-receive Hook (سمت سرور)


فایل زیر رو در پوشه ریپوزیتوری بسازید .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://github.community/t5/GitHub-Enterprise-Best-Practices/Using-pre-receive-hooks-in-GitHub-Enterprise/ba-p/13863


نیاز دیدم یه ترجمه فارسی از این فایل داشته باشیم

سعی میکنم با هر آپدیتش آپدیت کنم

اگر غلط املایی دیدین تو کامنتا بگید درست میکنم (تقصیر کیبوردمه 😉)