یک کامیت خوب گیت چگونه است؟

یک کامیت خوب در گیت باید دلیل تغییر در برنامه رو توضیح بده، قابل جستجو باشه، داستان تغییر رو تعریف کنه، آموزنده باشه و صادقانه نوشته شده باشه. در این نوشته نمونه ی یک کامیت خوب رو می بینیم که البته یه کامیت طولانیه و احتمالن برای هر تغییر حال نداشته باشیم (و شاید لزومی نداشته باشه) انقدر توضیح بنویسیم. اما به هر حال... :)

این نوشته ترجمه ای آزاده از «کامیت محبوب من در گیت» که 30 آگوست 2019 منتشر شده است.

این کامیت را وقتی در gov.uk کار می کردم، دیدم. کامیت رو دن کارلی نوشته بود و از این جا قابل دسترسه (و انتقادی که بهش شده هم همون جا قابل مشاهده است). یکی از ویژگی های مثبت متن باز بودن کد همینه که می شه مثال های آموزشی از کدها استخراج کرد و در کدزنی پیشرفت کرد.

اما چرا می گیم این یه کامیت مفیده؟ شاید در موارد مشابه یه کامیت با توضیحی شبیه یکی از موارد زیر کافی باشه:

change whitespace
fix bug

دلیل تغییر توضیح داده شده

این یه کامیت خوبه چون نه تنها توضیح داده که چی تغییر کرده بلکه در کنارش توضیح داده که چرا تغییر کرده.

I introduced some tests in a feature branch to match the contents of `/etc/nginx/router_routes.conf`. They worked fine when run with `bundle exec rake spec` or `bundle exec rspec modules/router/spec`. But when run as `bundle exec rake` each should block failed with:
    ArgumentError:
      invalid byte sequence in US-ASCII

بدون این توضیح احتمالن ما فکر می کردیم که این تغییر به خاطر خطای پارس کردن توی بعضی ابزارها بوده. نوشتن چنین جزئیاتی برای یه کار تیمی خیلی مهمه. چون وقتی مدتی از تغییر می گذره، هم فرد هم تیم یادش می ره دلیل تغییر چی بوده. به خصوص اگه فرد از اون تیم یا از اون شرکت بره.

قابل جستجوست

توی این کامیت، خطای مشاهده شده آورده شده و به همین دلیل قابل جستجوئه:

ArgumentError:
  invalid byte sequence in US-ASCII

افراد می تونن با دستور زیر یا با استفاده از قابلیت جستجوی کامیت گیتهاب، به این کامیت دسترسی پیدا کنند و ببینند کی قبلن به چنین خطایی برخورد کرده و چه جوری حلش کرده:

git log --grep &quotinvalid byte sequence&quot

داستان تغییر رو تعریف کرده

توی این کامیت با جزئیات توضیح داده شده که مشکل چی بوده و چه کارهایی برای حلش انجام شده و مسیر پیدا کردن راه حل هم گفته شده:

I eventually found that removing the `.with_content(//)` matchers made the errors go away. That there weren't any weird characters in the spec file. And that it could be reproduced by requiring Puppet in the same interpreter

یه کامیت آموزنده برای همه است

کاری که دن کرده اینه که مرحله به مرحله کارهایی رو که کرده توضیح داده و باعث می شه همه نکته های مفیدی درباره ی Unix toolset یاد بگیرند.

صادقانه نوشته شده

Now the tests work! One hour of my life I won't get back..

پاراگراف آخر کامیت، باعث می شه با متن همدلی پیدا کنیم و بدونیم دن واقعن برای این تغییر کوچیک زحمت کشیده.

البته که نمی شه انتظار داشت همه ی کامیت ها همین قدر پرجزئیات باشند اما به هر حال این یه نمونه ی خوب از کامیت مفید و آموزنده است.

مقاله ی «داستان گویی در نوشتن کامیت» و «شاخه ای در زمان: داستانی درباره ی بازبینی تاریخچه ها» به این نوشته مرتبطند.