├── README-FA.md └── README.md /README-FA.md: -------------------------------------------------------------------------------- 1 | # کامیت‌های بهتر گیت 2 | 3 | این آموزش همه اون چیزی هست نیاز دارید تا کامیت‌های گیت بهتری داشته باشید. 4 | 5 | ## قوانین 6 | 7 | من یه لیست ۱۰ تایی براتون تهیه کردم از مواردی که باعث میشه کامیت مسیج‌های حرفه‌ای داشته باشید: 8 | 9 | ### ۱. پیام‌های معنادار: 10 | 11 | اولین و مهم‌ترین قانون برای یک کامیت گیت همین مورد هست! هر کامیت مسیج باید یک پیام کامل، معنادار و مستقل داشته باشه. کامیت مسیج باید برای خواننده‌ی اون ارزشمند باشه. وقتی به گیت‌لاگ شما نگاه میکنم و کامیت مسیج‌هاتون رو میبینم باید همه‌چیز شفاف باشه و با خوندن فقط و فقط کامیت مسیج‌های شما بفهمم توی هر کامیت چه اتفاقی افتاده! بدون انجام هیچ کار اضافه‌ای! 12 | 13 | من چندتا مثال از کامیت مسیج‌های بد براتون تهیه کردم و پایین هرکدوم هم دلیل بد بودنش رو توضیح دادم. بریم ببینیم: 14 | 15 | 16 | ❌ `First commit` 17 | 18 | **چرا این مسیج بده؟** 19 | 20 | برای کسی که کامیت مسیج شما رو میخونه اهمیتی نداره که ببینه توی متن کامیت شماره کامیت رو نوشتید. چون این مساله رو میتونه با نگاه کردم به گیت‌لاگ خودش متوجه بشه. همینطور شما هیچ توضیحی در مورد اتفاقات رخ داده توی کامیت ندادید و در نتیجه خواننده اون هم هیچ ایده‌ای نداره! 21 | 22 | 23 | ❌ `Add some codes` 24 | 25 | **چرا این مسیج بده؟** 26 | 27 | وقتی که دارید روی پروژه و کدبیس کار میکنید، شما یا در حال **اضافه کردن** کد هستید، یا در حال **حذف کردن** کد یا **تغییر دادن** کد و هیچ بلای دیگه‌ای جز این موارد نمیتونید سر کدتون بیارید! بنابراین این کامیت مسیج هیچ فایده‌ای نداره و دردی رو دوا نمیکنه٬ شما باید بگید چی اضافه کردید نه اینکه فقط بگید کد اضافه کردید! 28 | 29 | 30 | ❌ `Refactoring and cleaning codes` 31 | 32 | **چرا این مسیج بده؟** 33 | 34 | من با خوندن این مسیج چطوری بفهمم که کدوم بخش کدبیس تغییرات و ریفکتور داشته؟ یا مثلا چطوری حدس بزنم چه نوع از ریفکتوری (مثلا کد اضافه حذف شده، پرفورمنس بالا رفته، خوانایی کد بیشتر شده یا ...) روی کدبیس اعمال شده؟ کامیت مسیج شما باید جواب این سوالات رو توی خودش داشته باشه! 35 | 36 | 37 | ❌ `Bug resolved` 38 | 39 | **چرا این مسیج بده؟** 40 | 41 | چه باگی برطرف شده؟ آیا باید حدس بزنم؟! طبیعتا نه، واسه همین لطفا لطفا صراحتا بگید چه باگی برطرف شده. 42 | 43 | 44 | ❌ `I added a new feature` 45 | 46 | **چرا این مسیج بده؟** 47 | 48 | به تکیه به مثال‌های قبلی، ما توی این مثال همچنان هیچ دیدی نسبت به تغییرات اتفاق افتاده توی کدبیس نداریم! ضمنا، نیازی نیست که اشاره کنید کی فیچر جدید اضافه کرده که ضمیر **من** اول کامیتتون استفاده کردید. خود گیت ثبت میکنه که صاحب هرکامیت کی هست. پس شما دوباره کاری نکنید! 49 | 50 | 51 | ### ۲. نه کم نه زیاد: 52 | 53 | اگه قصد دارید یه پیام معنادار برای کامتتون بنویسید، از نوشتن توضیحات طولانی خودداری کنید. همینطور بیش از حد هم خلاصه توضیح ندید. یکی از نشونه‌های کامیت مسیج خوب، داشتن طول مناسب هست (نه همیشه ولی اکثرا اینطوریه). شاید براتون سوال باشه که خب چرا توضیح کوتاه یا بلند خوب نیست؟ خیلیم عالی، بذارید با یه مثال براتون جا بندازم. 54 | 55 | فرض کنید رفیقم میخواد ازم پول قرض کنه. (مثلا من خیلی پول دارم :))))) ) 56 | 57 | ❌ `Please lend me money!` 58 | 59 | خب این مثال نمونه توضیح کوتاهه. توی این مثال رفیقم داره بهم میگه لطفا پول بهم قرض بده. همین! خب وقتی انقدر کوتاه و خلاصه این درخواست رو میگه بهم، من یسری سوالات برام به وجود میاد. مثلا اینکه چقدر پول میخواد؟ یا اینکه چه موقع پولمو برمیگردونه؟ اون باید خودش توی درخواستش این موارد رو بگه و منو مطلع کنه که من لازم نباشه ازش بپرسم. 60 | 61 | 62 | ❌ `Hey Ahmad, get on the bus as soon as it arrives at the bus station. Then go to your bank, fill out a form, and then get the money from the bank and lend me $20. I'm going to return it in three weeks.` 63 | 64 | خب متن بالا هم نمونه یه درخواست طولانی و بلنده. رفیقم بهم میگه احمد برو ایستگاه اتوبوس، هروقت انوبوس اومد سوارش شو و برو بانک. بعدش فرم بگیر، فرم رو پر کن، از حسابت پول برداشت کن و بهم ۲۰ میلیون بده (متن اصلیش بیست دلاره ولی مارو چه به دلار اون فقط مثاله). پولتم تا سه هفته آینده بهت برمیگردونم. 65 | 66 | خب میبینید که چقدر خسته کننده و غیر ضروری بوده نحوه درخواستش. لازم نبود بگه چطوری پولش رو جور کنم دیگه در اون حد بلدم! 67 | 68 | 69 | ✅ `Ahmad, please lend me 20 dollars. I will return it in 3 weeks` 70 | 71 | خب اینم مثال آدمیزادی و درست و درمون. مختصر و کوتاهه، ولی جای سوال خاصی باقی نمیمونه. 72 | 73 | **نکته کلیدی** 74 | 75 | متن کامیت مسیج شما، باید لُب مطلب و چکیده اتفاقات اصلی کامیت شما باشه. 76 | 77 | **نکته کلیدی** 78 | 79 | اگه فکر میکنید که واقعا هیچ‌جوره راه نداره که با یه پیام غیر طولانی چکیده کامیتتون رو توضیح بدید، به احتمال زیاد شما یه کامیت گنده دارید که باید به ۲ یا تعداد بیشتری کامیت کوچیک تقسیمش بکنید. 80 | 81 | 82 | ### ۳. از جملات دستوری استفاده کنید: 83 | 84 | وقتی میخواید کامیت مسیج بنویسید، فرض کنید که دارید به گیت دستور میدید. ازش درخواست نکنید یا بهش اطلاع رسانی نکنید. فقط مستقیما بهش دستور بدید! 85 | 86 | برای مثال فرض کنید یه تابع پیاده‌سازی کردید که قراره حروف کوچیک رو به حروف بزرگ تبدیل کنه: 87 | 88 | 89 | ❌ `Implementing a function that transform letters to upper case.` 90 | 91 | ترجمه مثال بالا: پیاده‌سازی تابعی که حروف کوچیک رو به بزرگ تبدیل میکنه. 92 | 93 | ❌ `I added a function to transforming letters to upper case.` 94 | 95 | ترجمه مثال بالا: من تابعی پیاده‌سازی کردم که حروف کوچیک رو به بزرگ تبدیل میکنه. 96 | 97 | ❌ `A function to transforming letters to upper case has been added.` 98 | 99 | ترجمه مثال بالا: تابعی اضافه شد که حروف کوچیک رو به بزرگ تبدیل میکنه. 100 | 101 | ✅ `Implement a function to transform letters to upper case` 102 | 103 | ترجمه مثال بالا: تابعی پیاده‌سازی کن که حروف کوچیک رو به بزرگ تبدیل میکنه. 104 | 105 | 106 | ### ۴. از توضیح جزئیات خودداری کنید: 107 | 108 | این قانون هم مکمل قانون دوم (نه کم نه زیاد) هست. لازم نیست همه چیز و همه جزئیات رو بگید. همیشه یادتون باشه که شما توی کامیت مسیج باید توضیح بدید که **چه چیزی** و **چرا** رو اضافه/حذف کردید یا تغییر دادید. نیازی نیست که بگید **چطور** این کار رو کردید. همچنین نیاز نیست تغییرات کم اولویت و خیلی کوچیک رو توی کامیت مسیج بنویسید. 109 | 110 | برای مثال، فرض کنید که تابعی به اسم getUser رو میخواید ریفکتور کنید. بعد از اینکه ریفکتورش کردید، متوجه میشید که یه متغیر بدون استفاده داخل تابعتون دارید. بنابراین طبیعتا اون متغیر رو حذف میکنید. خب اینجا دیگه نیازی نیست که حذف کردن این متغیر هم توی کامیت مسیجتون گفته بشه. مثل مثال زیر که یه مثال بد هست: 111 | 112 | ❌ `Refactor the 'getUser' function and delete an unused variable in its related file.` 113 | 114 | واسه چی نیازی نیست که به حذف این متغیر اشاره بشه؟ چون حذف این متغیر از تابع، هدف اصلی این کامیت نبوده. در واقع یه تغییر کوچیک بوده که ما در طول کار اصلی و هذف اصلی کامیتمون، اعمال کردیم. البته شما میتونید این متغیر رو توی یه کامیت جداگانه حذف کنید. یا اینکه مثالا میتونید یه تسک جدید تعریف بکنید برای حذف کردن تمام متغیرهای بلااستفاده تو کدبیس و بنابراین میتونید همه اونا رو توی یه کامیت از کدبیستون حذف بکنید. 115 | 116 | خب از بحث اصلی دور نشیم. توی مثالی که زدم، من این کامیت مسیج رو ترجیح میدم به کامیت مسیج بالایی: 117 | 118 | ✅ `Refactor the 'getUser' function` 119 | 120 | 121 | ### ۵. پیشوندهای مفهومی 122 | 123 | این مورد یه چیز اختیاریه که اگه دوست داشتید میتونید ازش استفاده بکنید. چون باعث میشه کامیت مسیج‌های خوانا و قدرتمندی داشته باشید. برحسب اینکه توی کامیت مربوطه، چه نوع تغییراتی توی کدبیس اعمال کردید، میتونید از یه پیشوند مناسب و درخور براش استفاده کنید. پیشوندها همونطور که از اسمشونم مشخصه، معمولا اول کامیت مسیج استفاده میشن. 124 | 125 | من یه لیست از پیشوندهای معروف رو که خیلی زیاد دیدم و خودمم استفاده میکنم براتون مینویسم: 126 | 127 | * `[BUGFIX]`: برای مواردی که باگی توی کدبیس برطرف شده استفاده میشه. 128 | * `[TEST]`: برای وقتایی که تست نویسی کردیم (حالا هر نوع تستی مثل یونیت تست، یوزراستوری و ...) 129 | * `[FEATURE]`: اینم واسه وقتی که یه فیچر جدید به کدبیس اضافه میشه. 130 | * `[REFACTOR]`: این پریفیکس وقتی استفاده میشه که کدبیس رو ریفکتور کردیم. حالا چه در راستای خوانایی، چه بهبود عملکرد و ... . 131 | * `[UPDATE]`: برای وقتایی که یک کتابخونه یا وابستگی رو آپدیت میکنیم. همچنین واسه وقتایی که یه فیچر موجود رو، بخاطر آپدیت شدن داکیومنت‌ها، آپدیت میکنیم و تغییرات روش اعمال میشن. 132 | * `[BASE]`: برای نصب کتابخونه‌ها و وابستگی‌های پروژه. یا برای وقتایی که یسری زیرساخت‌های پروژه‌ای رو تنظیم و اعمال میکنیم. مثل ست کردن تنظیمات پروژه و کتابخونه‌ها و ... . 133 | * `[DOCS]`: برای وقتای که میخوایم به داکیومنت‌هامون چیزی اضافه کنیم یا تغییرشون بدیم. 134 | 135 | موارد بالا فقط یسری پیشوندهای پیشنهادی بودن و هیچ اجباری برای استفاده از اون‌ها نیست. ولی من اینارو توی خیلی از پروژه‌ها دیدم. ضمن اینکه انصافا اسماشون خیلی ساده و بدیهیه. حالا شما اگه حال نکردید باهاشون، میتونید پیشوندهای خودتون رو داشته باشید! 136 | 137 | **نکته کلیدی** 138 | 139 | حروف پیشوندها میتونن همشون حروف کوچیک باشن. فقط لطفا یه یه قاعده ثابت پیروی کنید. برای مثال اگه از حروف کوچیک استفاده کردید، تا آخر داستان ریپازیتوریتون، فقط ار حروف کوچیک استفاده بکنید برای پیشوندها. 140 | 141 | 142 | ### ۶. لطفا بیخیال اموجی بشید: 143 | 144 | اخیرا زیاد دیدم که توسعه‌دهنده‌ها از اموجی توی کامیت مسیج‌هاشون استفاده میکنن. این کار اصلا خوب نیست. میگید چرا؟ به دو دلیل: 145 | 146 | 147 | * اونا معنا و پیام کاملا مشخص و ثابتی ندارن. 148 | * اموجی‌ها از یونیکد‌های خاصی استفاده میکنن. بنابراین ممکنه یه روزی ما با ترمینالی کار بکنیم که الزاما تمام یونیکدهارو پشتیبانی نمیکنه و بنابراین، توی اون ترمینال ما نمیتونیم اموجی‌ها رو ببینیم. 149 | 150 | یکی از همکارهای من نظر مخالف داره و میگه که استفاده از اموجی خوبه. اون معتقده که هر اموجی واقعا یه معنا ثابت و خاصی داره و بنابراین میشه ازشون تو کامیت مسیج استفاده کرد. برای مثال اون اموجی یه کرم رو (🐛) بهم نشون داد و گفت همه میدونن که معنی اموجی کرم یعنی باگ! من بهش گفتم باشه قبوله. اما برای تست۷ فیچر، ریفکتور و ... از چه اموجی‌هایی باید استفاده کرد؟ اون یه وب‌سایت بهم معرفی کرد که توی اون کلی اموجی معرفی کرده بودن و برای هر کدوم هم یه توضیح و معنی خاص و متفاوت با بقیه ارائه کرده بودن. 151 | 152 | این آدرس اون سایته: 153 | 154 | [Gitmoji](https://gitmoji.dev) 155 | 156 | اما من با همکارم مخالفم چون سایت بالا یه رفرنس برای کامیت‌های گیت نیست. این سایت محصول یه کمپانی معروف با استاندارهای بالا نیست. فقط یه آدم خوش ذوق یکسری اموجی معرفی کرده و طبق سلیقه خودش برای هرکدوم یه معنی نوشته. همین و نه بیشتر! 157 | 158 | اگه یه روزی ترمینال‌ها از عکس‌ها هم پشتیبانی کنن و بشه تو اون‌ها عکس هم نشون داد، من میتونم یه سایت درست کنم برای استفاده از عکس توی کامیت مسیج‌ها! مثلا یه عکس میذارم از مردی که ترسیده و توضیحات عکسشم بنویسم که این عکس به باگ اشاره میکنه! خب این که نشد استاندار :) 159 | 160 | 161 | ### ۷. پیشوندهای ارجاع‌دهنده: 162 | 163 | این موردم شبیه به مورد شماره پنج (پیشوندهای مفهومی) هست با یه فرق اساسی: پیشوندهای ارجاع‌دهنده یه معنی مستقیم و واضح دارن که دیدنشون میشه فهمید اون کامیت حول چه چیزی (باگ، تست، فیچر و ...) بوده. ولی پیشوندهای اجراع‌دهنده به توضیحات خارجی اشاره میکنن. مثلا به یه تسک روی جیرا، به یه کارت ترلو یا یک ایشو روی گیت‌لب یا هرچیز دیگه‌ای. پیشوندهای ارجاعی معمولا تو تیم‌های بزرگ و تیم‌های بر پایه‌ی اسکرام استفاده میشه. 164 | 165 | برای استفاده از یه پیشوند ارجاعی راه‌های مختلفی هستن. من چند استایل پر استفاده و معروف رو اینجا مینویسم: 166 | 167 | * `[#]`, `[#]` or `[#]` 168 | * `[]`, `[]` or `[]` 169 | * `()`, `()` or `()` 170 | 171 | 172 | یه مثال از موارد بالا: 173 | 174 | * `[#217] Resolve the bug of 'fetchUsers' function that causes some users be missed` 175 | 176 | اون [#217] که اول کامیت نوشته شده، میتونه به این اشاره داشته باشه که این کامیت متعلق به تسک شماره ۲۱۷ هست. حالا اهمیتی نداره که شما از چه سرویس مدیریتی برای تسک‌هاتون استفاده میکنید. در هرصورت شما میتونید از این پیشوندها برای اشاره به یک تسک/باگ/کارت از تسک منیجرتون اشاره کنید. 177 | 178 | **نکته کلیدی** 179 | 180 | شما میتونید از پیشوندهای مفهومی و پیشوندهای ارجاع‌دهنده کنار همدیگه استفاده کنید. این به تصمیم شما بستگی داره. 181 | 182 | من چندتا مثال از استفاده پیشوندهای مفهومی و ارجاع‌دهنده کنار همدیگه آماده کردم: 183 | 184 | * `[#REFACTOR](217) Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase` 185 | 186 | * `[REFACTOR-217] Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase` 187 | 188 | * `[#217][REFACTOR] Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase` 189 | 190 | همه مثال‌های بالا فقط یه الگو هستن برای درک بهتر شما. پس یه قاعده دقیق و الزامی نیستن. شما میتونید اون‌هارو به هر شکلی که خواستید کنار همدیگه استفاده کنید. ولی موارد بالا چیزایی بودن که من بیشتر به چشمم خورده که شرکت‌ها و تیم‌ها ازشون پیروی میکردن. 191 | 192 | 193 | ### ۸. جداسازی ارجاعات به کدبیس و اصطلاحات تخصصی: 194 | 195 | بعضی وقتا کامیت مسیج‌ها به اسم یه متغیر، تابع، متد یا کلاس اشاره میکنن یا اینکه یه کلمه یا اصطلاح تخصصی توشون نوشته میشه. توی همچین مواقعی که نیاز دارید همچین چیزایی توی کامیت مسیجتون باشه، نام اون متغیر، تابع، کلاس، متد، اصطلاح تخصصی یا هرچیز مشابه رو بین بک‌تیک یا کوتیشن قرار بدید تا از بقیه کلمات عادی تفکیک و تمیز داده بشن. 196 | 197 | 198 | ❌ `Upgrade Jest and React Testing Library to the latest versions` 199 | 200 | ✅ `Upgrade 'Jest' and 'React Testing Library' to the latest versions` 201 | 202 | ❌ `Use for-in loop instead of for-of loop inside calculatePrice function` 203 | 204 | ✅ `Use 'for-of' loop instead of 'for-in' loop inside the 'calculatePrice' function` 205 | 206 | ### ۹. نکات بیشتر: 207 | 208 | * همیشه کامیت مسیج‌هاتون رو فقط و فقط و فقط به انگلیسی بنویسید و نه هیچ زبان دیگه‌ای! 209 | * آخر کامیت مسیج‌هاتون نقطه نذارید. 210 | * حرف اول کامیت مسیج‌هاتون رو بزرگ بنویسید. 211 | * تعداد کاراکترهای کامیت مسیجتون بیشتر از ۷۲ تا نشه. (البته که همیشه استثنا وجود داره) 212 | * از لینک‌ و یو‌آر‌ال توی کامیت مسیجتون استفاده کنید. 213 | 214 | 215 | ### ۱۰. لاگ یک دست داشته باشید: 216 | 217 | اگه یه چرخی تو خیلی از ریپازیتوری‌های معروف بزنید، میبینید که بعضا خیلی تفاوت‌های فاحشی بین کامیت مسیج‌ها وجود داره. برای مثال، یسریاشون پیشوند دارن یسریا نه، یسریاشون جملاتشون حالت دستوری داره، یسریاشون خبری، یسریاشون حرف اول بزرگه، یسریاشون نه، یسریاشون اموجی دارن یکسری نه و ... .این اتفاق معمولا به این دلیل رخ میده که افراد و تیم‌ها قوانین مشخصی رو پیروی نمیکنن. همیشه یه راهنمای جامع و شفاف برای خودتون و اعضای تیمتون داشته باشید. با رعایت این مساله، شما میتونید از جلوی کامیت های غیر همسان و جورواجور رو بگیرید. 218 | 219 | همچنین میتونید از یسری ابزارهای خارجی و لینترها کمک بگیرید تا کامیت‌هاتون رو به قول معروف دبل‌چک بکنید (دوبار چک بکنید). لینترها و ابزارهای خارجی تضمین میکنن که کامیت مسیج‌هاتون تداخلی با قواعدی که براشون اعمال کردید نداشته باشن. در واقع اونا شما و تیمتون رو مجبور میکنن که از قوانین مشخصی برای کامیت مسیج‌هاتون پیروی بکنید. 220 | 221 | 222 | **اگه این ریپازیتوری بهتون کمک کرد، ستاره دادنو فراموش نکنید ;)** 223 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Better Git Commits 2 | 3 | This is everything you need to know about having better Git commit messages. 4 | 5 | 6 | ## Rules 7 | 8 | I listed 10 rules for having a professional commit message. 9 | 10 | ### 1. Meaningful messages: 11 | 12 | The first and the most important rule for a Git commit message is this! Each commit message must have a complete, meaningful and independent description. Commit message has to be valuable for its readers. As a reader, when I'm looking at the Git's log of your repository, All the commit messages must be clear for me and I should be aware about the changes of each commit, just by a simple look! 13 | 14 | I prepared some examples of bad commit messages and I explained why they are bad, so look at these: 15 | 16 | 17 | ❌ `First commit` 18 | 19 | 🔷 **Why it's bad?** 20 | > It's not important for the reader to know about the number of commits in its message. Because he/she can be aware about it, by a looking to the Git's log. Also he/she can't have any idea about what's happening in the codebase in this commit! 21 | 22 | ❌ `Add some codes` 23 | 24 | 🔷 **Why it's bad?** 25 | > When you work on a codebase, you can **add**, **delete** or **modify** the code and there is no any other options! So, it has not any benefits for the reader! You must say what you added! 26 | 27 | ❌ `Refactoring and cleaning codes` 28 | 29 | 🔷 **Why it's bad?** 30 | > How can I be informed that which section of the codebase has been modified? Or how can I guess what type of refactoring has been applied on the codebase? Your commit message have to include the answer of these questions in self! 31 | 32 | ❌ `Bug resolved` 33 | 34 | 🔷 **Why it's bad?** 35 | > Which bug is resolved? must the reader guess the bug?! Of course not, so please explain which bug is resolved explicitly. 36 | 37 | ❌ `I added a new feature` 38 | 39 | 🔷 **Why it's bad?** 40 | > According to the previous examples, here we haven't any clear vision about the modifications of the codebase! Btw, there is no need to use pronoun at the first of this commit message. Git saves the author of each commit by itself and we haven't to do a duplicated action! 41 | 42 | 43 | ### 2. Neither Long nor Short: 44 | 45 | If you want to write a meaningful message for a commit, avoid writing lengthy descriptions. Very summarized texts too! A sign of a good commit message is a suitable length most of the time. Maybe you want to know why we should avoid long/short messages in our commit messages? Well, here's an example. 46 | 47 | Assume my friend asks me to lend him some money. 48 | 49 | ❌ `Please lend me some money!` 50 | > It's an example of a short message. When my friend tells it, I ask two related questions: "How much money do you need?" and "When will you get it back?". He could make me clear about them, so there was no need to these questions. 51 | 52 | ❌ `Hey Ahmad, get on the bus as soon as it arrives at the bus station. Then go to your bank, fill out a form, and then get the money from the bank and lend me $20. I'm going to return it in three weeks.` 53 | > This is an example of a long message. It's an example of a long message. Don't tell me how can I provide some money! Just tell me your request. 54 | 55 | ✅ `Ahmad, please lend me 20 dollars. I will return it in 3 weeks.` 56 | > Perfect! It's that I want to hear! 57 | 58 | 59 | 🔑 *The text of your message, must be the gist of your commit.* 60 | 61 | 🔑 *If you think that you need a long text to tell the gist of your commit, probably you have a big commit that should be separated in 2 or more smaller commits.* 62 | 63 | 64 | ### 3. Use Imperative Mood: 65 | 66 | When you want to write a commit message, suppose you give Git an order. Do not ask or inform Git! Just command directly! 67 | 68 | For example, suppose you implemented a function that can transform the characters of a text into the upper case characters. 69 | 70 | ❌ `Implementing a function that transforms letters to upper case.` 71 | 72 | ❌ `I added a function to transform letters to upper case.` 73 | 74 | ❌ `A function that transforms letters to upper case has been added.` 75 | 76 | ✅ `Implement a function to transform letters to upper case.` 77 | 78 | 79 | ### 4. Avoid Writing Details: 80 | 81 | This rule complements the `Neither Long nor Short` rule. No need to write everything in details. 82 | Always remember, you must tell `What` and `Why` something added/removed/modified in the codebase, not `How`! Also, no need to write the bit or low-priority modifications. 83 | 84 | For example, assume you want to refactor a function named getUser in your codebase. After refactoring it, you may notice that the related file has an unused variable inside of itself, so you decide to remove it. When you want to commit your changes, there is no need to write something like this: 85 | 86 | ❌ `Refactor the 'getUser' function and delete an unused variable in its related file.` 87 | 88 | Why it's not necessary to refer to the delete variable? Because it wasn't the primary goal of this commit. It was a minor modification that we could fix along with another commit. Of course, you can delete this unused variable in a separate commit, or maybe you want to make a new task for your project to find all unused variables and remove them all in a commit! 89 | 90 | I prefer this one: 91 | 92 | ✅ `Refactor the 'getUser' function.` 93 | 94 | 95 | ### 5. Conceptual Prefixes: 96 | 97 | This one is an optional offer for your commit messages but can make them very readable and powerful. According to the added modifications in the codebase in your commit, you can use a suitable and matched prefix for its message. In most cases, prefixes are used at the first of commit messages. 98 | 99 | Here is a list of the most usable prefixes that I often see in software teams: 100 | 101 | * `[BUGFIX]`: For resolving any bug and issues from the codebase. 102 | * `[TEST]`: For writing any type of tests (Unit / End-to-End / UserStory / Integration / Regression / ...) 103 | * `[FEATURE]`: For adding a new feature and implementation 104 | * `[REFACTOR]`: For improving current codes for any purpose like better readability, performance, etc. 105 | * `[UPDATE]`: For updating libraries and dependencies, also updating current features by documentation. 106 | * `[BASE]`: For installing new libraries and dependencies and setting up the infrastructures of the codebase, like configuring the project and its packages. 107 | * `[DOCS]`: For adding or modifying the documentations. 108 | 109 | The above cases are only some offers for you so, there isn't any force to use them. You can have your own! 110 | 111 | 🔑 *The text of your prefixes can be lowercase. Please follow a fixed rule. For example, if you want to write your prefixes in lowercase, write them all in lowercase forever in the related repository.* 112 | 113 | 114 | ### 6. Emoji? Please No! 115 | 116 | Recently I've seen developers using emojis in their commit messages. In my opinion, it's not a good practice! Say Why? Because of two reasons: 117 | 118 | * They don't have a clear message. 119 | * Emojis have specific Unicode, maybe we have a terminal that doesn't support those Unicode, so we can't see any emojis in our terminal. 120 | 121 | One of my colleagues disagreed with me about the case one. She believed that each emoji has a special meaning, and we can use them in our commit messages. I asked her to give an example. She showed the emoji of a worm (🐛) and said that everybody knows that this emoji refers to a bug! I asked her what should be used for features, refactoring, testing, and ...? She introduced a website to me and she said they provide lots of emojis and have a unique meaning for all of them. 122 | 123 | It's the address of that website: [Gitmoji](https://gitmoji.dev) 124 | 125 | I disagree with my colleague because this website is not a reference for git commits! It's not the product of a famous company with high-level standards! Only one tasteful person has presented some emojis and has written explanations for each of them according to his taste. And nothing more! 126 | One day, if terminals support showing images, I can create a website for using images in the commit messages! For example, I can provide the picture of a scared man and say that refers to a bug! It's not standard :) 127 | 128 | 129 | ### 7. Referral Prefixes: 130 | 131 | This case is similar to `Conceptual Prefixes` with a main difference: The *Conceptual Prefixes* have a straight and clear message for their readers and they directly say their content. But the *Referral Prefixes* point to a external description, like a task on Jira, a card on Trello, an issue on Gitlab or anything else! *Referral Prefixes* usually be used in the large teams and teams that they use Scrum methodology. 132 | 133 | For using a referral prefix, there are some common styles that I listed: 134 | 135 | * `[#]`, `[#]` or `[#]` 136 | * `[]`, `[]` or `[]` 137 | * `()`, `()` or `()` 138 | 139 | 140 | As an example of the above cases: 141 | 142 | * `[#217] Resolve the bug of 'fetchUsers' function that causes some users to be missed` 143 | 144 | > [#217] the first part of this commit can refer to a task number 217. It's no matter which tasks manager you are using. You can always use these referral prefixes to point your tasks/cards/issues. 145 | 146 | 147 | 🔑 *You can use both **Conceptual Prefixes** and **Referral Prefixes** together. It is related to your decision.* 148 | 149 | I listed some examples for the usage of conceptual prefixes and referral prefixes side by side: 150 | 151 | 152 | * `[#REFACTOR](217) Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase` 153 | 154 | * `[REFACTOR-217] Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase` 155 | 156 | * `[#217][REFACTOR] Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase` 157 | 158 | 159 | 🔑 *The above examples are just some template and they are not some rules. You can use them in any other styles.* 160 | 161 | 162 | ### 8. Separate References to The Codes and Specialized Terms 163 | 164 | Sometimes commit messages contain references to variables, functions, methods, classes, and specialized terms. Whenever you need to write a specialized term or the name of a variable/function/method/class or anything similar, wrap its name in a couple of backticks or quotation marks. It helps the reader detect that the wrapped word is different from the others and there is a reference to the codebase. 165 | 166 | 167 | ❌ `Upgrade Jest and React Testing Library to the latest versions` 168 | 169 | ✅ `Upgrade 'Jest' and 'React Testing Library' to the latest versions` 170 | 171 | ❌ `Use for-in loop instead of for-of loop inside calculatePrice function` 172 | 173 | ✅ `Use 'for-of' loop instead of 'for-in' loop inside the 'calculatePrice' function` 174 | 175 | ### 9. Extra Tips 176 | 177 | * Write your messages just in English! Not any other language. 178 | 179 | * Don't put dot (`.`) at the end of your messages. 180 | 181 | ❌ `Install 'Redux' and 'Redux Toolkit' libraries.` 182 | 183 | ✅ `Install 'Redux' and 'Redux Toolkit' libraries` 184 | 185 | 186 | * Capitalize the first letter of the commit message. 187 | 188 | ❌ `write integration test for 'Settings' module` 189 | 190 | ✅ `Write integration test for 'Settings' module` 191 | 192 | 193 | * Wrap lines at 72 characters. (Always there exists some exceptions) 194 | 195 | * Don't use urls in the messages. 196 | 197 | ### 10. Have a Coherent Log! 198 | 199 | If you have a tour in the log of lots of the famous repositories, you can see a lot of differences between commit messages. For example, some of them have prefixes, and some other have'nt. Some of them include emojis, some of them no. Some start with a capitalized letter, some of them no, etc. It usually happens because teams and people don't follow typical rules. Always have a complete and clear guideline for yourself and your team. By doing it, you can prevent having inconsistent commit messages. 200 | 201 | You can use some external tools and linters for double-checking the commits. Linters and these external tools, ensure that no commit message will conflict with the rules you applied. They force you and your team members to follow the rules. 202 | 203 | 204 | **If this repository helped you, don't forgive getting a star ;)** 205 | --------------------------------------------------------------------------------