پرش به مطلب اصلی

گردش کار گیت

مرور کلی​

تیم ما از یک گردش کار ساختار یافته گیت پیروی می‌کند تا کیفیت کد، قابلیت نگهداری و همکاری را تضمین کند. این سند شیوه‌ها و قراردادهای گیتی را که بر سر آن‌ها توافق کرده‌ایم، تشریح می‌کند.

ساختار شاخه‌ها​

شاخه‌های اصلی​

  • main: کد آماده تولید، همیشه قابل استقرار است. توسعه‌دهندگان مستقیماً روی این شاخه کار نمی‌کنند. تغییرات از شاخه استیجینگ به طور خودکار در زمان‌های برنامه‌ریزی شده از طریق Laravel Forge به شاخه main منتقل می‌شوند.
  • staging: محیط آزمایشی قبل از تولید. اصلاحیه‌های اضطراری از این شاخه ایجاد شده و به آن ادغام می‌شوند.
  • develop: شاخه ادغام برای ویژگی‌های جدید. کارهای توسعه‌ای معمول از این شاخه منشعب شده و به آن ادغام می‌شوند.

گردش کار شاخه‌ها​

  • توسعه عادی: توسعه‌دهندگان از شاخه develop انشعاب می‌گیرند و تغییرات را از طریق درخواست ادغام به develop بازمی‌گردانند.
  • اصلاحیه‌های اضطراری: برای مسائل بحرانی، توسعه‌دهندگان از شاخه staging انشعاب می‌گیرند و تغییرات را از طریق درخواست ادغام به staging بازمی‌گردانند.
  • انتخابی‌کردن تغییرات (Cherry-picking): CTO مسئول انتخاب و انتقال تغییرات بین شاخه‌های staging و develop برای همگام‌سازی آن‌ها است.

شاخه‌های پشتیبان​

  • feature/[نام-ویژگی]: ویژگی‌ها یا بهبودهای جدید
  • fix/[توضیح-ایراد]: رفع ایرادات غیرحیاتی
  • hotfix/[توضیح-اصلاحیه]: رفع ایرادات بحرانی تولید
  • change/[توضیحات]: تغییرات در عملکرد موجود
  • improvement/[توضیحات]: بهبود در ویژگی‌های موجود
  • update/[توضیحات]: به‌روزرسانی وابستگی‌ها یا پیکربندی‌ها
  • SDK/[توضیحات]: تغییرات مرتبط با SDK

قراردادهای نام‌گذاری شاخه‌ها​

اجرای سخت‌گیرانه

شاخه‌هایی که از این قراردادها پیروی نکنند، منجر به بسته شدن فوری درخواست‌های ادغام خواهند شد.

نام شاخه‌ها باید از دو بخش تشکیل شده باشد که با اسلش (/) از هم جدا شده‌اند:

۱. نوع: نوع کاری که انجام می‌شود را مشخص می‌کند ۲. توضیحات: شرح کار واقعی را ارائه می‌دهد

(hotfix|fix|change|feature|improvement|SDK|update)/what-we-do

بخش توضیحات باید از قراردادهای slug پیروی کند (حروف کوچک با خط تیره برای جدا کردن کلمات).

نمونه‌های معتبر:

  • hotfix/mass-notif
  • feature/user-authentication
  • fix/login-validation
  • change/payment-flow
  • improvement/dashboard-performance
  • SDK/client-update
  • update/dependencies

نمونه‌های نامعتبر:

  • bug/login-issue (نوع نادرست)
  • feature_user_auth (جداکننده نادرست)
  • hotfix/Mass-Notification (حروف نادرست)

دستورالعمل‌های کامیت​

قالب پیام کامیت​

ما از یک قالب ساختاریافته برای پیام‌های کامیت استفاده می‌کنیم:

[type]: خلاصه کوتاه (حداکثر 50 کاراکتر)

توضیحات دقیق در صورت لزوم. خط‌ها حداکثر 72 کاراکتر باشند.
توضیح دهید چه تغییری و چرا ایجاد شده است، نه چگونه (کد این را نشان می‌دهد).

رفع #123

انواع کامیت​

  • feat: ویژگی جدید
  • fix: رفع ایراد
  • docs: تغییرات مستندات
  • style: تغییرات قالب‌بندی (فاصله‌ها، قالب‌بندی و ...)
  • refactor: تغییر کد که نه ایرادی را رفع می‌کند و نه ویژگی جدیدی اضافه می‌کند
  • test: اضافه کردن یا به‌روزرسانی تست‌ها
  • chore: تغییرات در فرآیند ساخت یا ابزارهای کمکی
  • perf: بهبودهای عملکردی

بهترین روش‌های کامیت​

  • کامیت‌های اتمی ایجاد کنید (یک تغییر منطقی در هر کامیت)
  • پیام‌های کامیت توصیفی بنویسید
  • به شماره‌های مسئله در پیام‌های کامیت ارجاع دهید
  • کد کامنت‌گذاری شده را کامیت نکنید
  • کد دیباگ یا لاگ‌های کنسول را کامیت نکنید
  • فایل‌های تولید شده یا وابستگی‌ها را کامیت نکنید

بررسی کیفیت کد قبل از کامیت​

اجرای سخت‌گیرانه

قبل از ارسال کد برای بررسی، همه توسعه‌دهندگان باید لینترها و فرمترها را روی کد خود اجرا کنند.

دستور زیر را برای بررسی آخرین کامیت اجرا کنید:

php artisan code:run-all lastcommit

این دستور:

  • تمام لینترها را روی کد شما اجرا می‌کند
  • کد شما را مطابق با استانداردهای پروژه فرمت می‌کند
  • مشکلات رایج و نقض استانداردهای کدنویسی را بررسی می‌کند

اگر دستور هرگونه مشکلی را گزارش داد، قبل از ایجاد درخواست ادغام آن‌ها را برطرف کنید. درخواست‌های ادغام با مشکلات لینتینگ یا قالب‌بندی رد خواهند شد.

فرآیند درخواست ادغام​

ایجاد درخواست‌های ادغام​

۱. یک شاخه از شاخه پایه مناسب ایجاد کنید (develop برای کارهای عادی، staging برای اصلاحیه‌های اضطراری) ۲. تغییرات خود را در کامیت‌های کوچک و منطقی انجام دهید ۳. لینترها و فرمترها را اجرا کنید (php artisan code:run-all lastcommit) ۴. شاخه خود را به مخزن ریموت فشار دهید ۵. یک درخواست ادغام با عنوان و توضیحات توصیفی ایجاد کنید ۶. قالب PR را به طور کامل پر کنید ۷. بازبین‌ها را تعیین کنید (حداقل ۲ نفر، شامل CTO) ۸. مسائل مرتبط را پیوند دهید

الزامات توضیحات PR​

اجرای سخت‌گیرانه

درخواست‌های ادغامی که از این دستورالعمل‌های توضیحات پیروی نکنند، ادغام نخواهند شد.

توضیحات PR باید جامع و خودکفا باشند:

  • به وظایف، سنتری یا تلسکوپ به جای توضیحات مناسب ارجاع ندهید
  • توضیحات کاملی از تغییرات انجام شده و دلایل آن بنویسید
  • برای به‌روزرسانی بسته‌ها (به‌ویژه به‌روزرسانی‌های سمت کلاینت SDK)، تمام تغییرات نسخه جدید را به‌طور صریح فهرست کنید

ساختار الزامی توضیحات PR​

اجرای سخت‌گیرانه

درخواست‌های ادغامی که از این ساختار دقیق پیروی نکنند، بلافاصله بسته خواهند شد. باید یک PR جدید با ساختار صحیح ایجاد کنید.

تمام توضیحات درخواست‌های ادغام باید دقیقاً از این ساختار پیروی کنند:

وظیفه مرتبط: (URL وظیفه Trello)
توضیحات: (توضیح واضحی از تغییرات انجام شده)
چک‌لیست تست:
- مورد اول
- مورد دوم
- مورد سوم

در چک‌لیست تست، مواردی را که باید پس از ادغام این PR آزمایش شوند، فهرست کنید:

  • مواردی که نیاز به تست دارند
  • مواردی که مستقیماً با وظیفه مرتبط هستند
  • مواردی که ممکن است تحت تأثیر عوارض جانبی تغییرات شما قرار گیرند

قالب PR​

## وظیفه مرتبط
[URL وظیفه Trello را اینجا وارد کنید]

## توضیحات
[توضیح دهید چه تغییراتی ایجاد کرده‌اید - به وضوح و با جزئیات]

## چک‌لیست تست
- [اولین موردی که نیاز به تست دارد]
- [دومین موردی که نیاز به تست دارد]
- [سومین موردی که نیاز به تست دارد]

## به‌روزرسانی بسته‌ها (در صورت وجود)
- [نام بسته] از [نسخه قدیمی] به [نسخه جدید] به‌روزرسانی شد
- تغییرات در این نسخه:
  - [لیست تمام تغییرات مهم در نسخه جدید]
  - [تغییرات شکست‌ناپذیر را ذکر کنید]

## نوع تغییر
- [ ] رفع اشکال
- [ ] ویژگی جدید
- [ ] تغییر شکست‌ناپذیر
- [ ] به‌روزرسانی مستندات

## این تغییرات چگونه تست شده‌اند؟
[رویکرد تست را شرح دهید]

## چک‌لیست
- [ ] کد من از استانداردهای کدنویسی پروژه پیروی می‌کند
- [ ] تست‌هایی اضافه کرده‌ام که ثابت می‌کند رفع اشکال/ویژگی کار می‌کند
- [ ] در صورت لزوم مستندات را به‌روزرسانی کرده‌ام
- [ ] تمام تست‌ها به صورت محلی با موفقیت اجرا می‌شوند

مدیریت تعارضات و تغییرات نامرتبط​

اجرای سخت‌گیرانه

درخواست‌های ادغامی که حاوی کامیت‌ها یا فایل‌های نامرتبط از سایر توسعه‌دهندگان باشند، ادغام نخواهند شد.

زمانی که شاخه شما حاوی تغییرات نامرتبط است:

۱. مسئولیت پاکسازی شاخه بر عهده شماست ۲. می‌توانید از تکنیک‌های rebase یا merge به دلخواه خود استفاده کنید ۳. CTO در حل این مسائل کمکی نخواهد کرد ۴. مشکل باید ۱۰۰٪ برطرف شده باشد تا PR ادغام شود

روش پیشنهادی برای پاکسازی شاخه‌ها​

# گزینه ۱: استفاده از rebase برای پاکسازی شاخه شما
git checkout develop  # یا برای اصلاحات اضطراری از staging استفاده کنید
git pull
git checkout your-branch
git rebase -i develop  # یا برای اصلاحات اضطراری از staging استفاده کنید
# در rebase تعاملی، فقط کامیت‌های خود را نگه دارید و بقیه را حذف کنید

# گزینه ۲: ایجاد یک شاخه تمیز
git checkout develop  # یا برای اصلاحات اضطراری از staging استفاده کنید
git pull
git checkout -b clean-branch-name
git cherry-pick <هش-کامیت-شما>
# سپس یک PR جدید از شاخه تمیز ایجاد کنید

مدیریت تعارضات​

هنگام بروز تعارض:

۱. آخرین تغییرات را از شاخه پایه (develop یا staging) دریافت کنید ۲. تعارضات را به صورت محلی حل کنید ۳. پس از رفع تعارض، به طور کامل تست کنید ۴. تغییرات حل‌شده را فشار دهید ۵. راه‌حل‌های پیچیده تعارض را در PR مستند کنید

فرآیند انتشار​

فرآیند انتشار گیت ما:

۱. تغییرات از طریق فرآیند PR به شاخه develop ادغام می‌شوند ۲. شاخه staging با تغییرات develop به‌روزرسانی می‌شود (توسط CTO مدیریت می‌شود) ۳. تست‌ها بر روی محیط staging انجام می‌شود ۴. در زمان‌های برنامه‌ریزی شده، تغییرات از staging به طور خودکار از طریق Laravel Forge به main منتشر می‌شوند ۵. برای اصلاحات اضطراری، تغییرات مستقیماً به staging ادغام شده و سپس توسط CTO به develop منتقل می‌شوند

هوک‌های گیت​

ما از هوک‌های گیت برای اعمال کیفیت استفاده می‌کنیم:

  • pre-commit: اجرای لینتینگ و فرمت‌بندی
  • pre-push: اجرای تست‌ها
  • commit-msg: اعتبارسنجی قالب پیام کامیت

یکپارچه‌سازی مستمر​

خط لوله CI ما بر روی تمام درخواست‌های ادغام اجرا می‌شود:

۱. ساخت پروژه ۲. اجرای لینتینگ و تحلیل استاتیک ۳. اجرای تست‌های واحد و یکپارچه‌سازی

آخرین به روز رسانی در تاریخ توسط Behnam Moradi