اولین Pull Requestی که در یک تیم حرفه‌ای فرستادم، سیصد خط تغییر در یک کامیت بود. ریویوئر بعد از دو روز جواب داد: نمی‌دانم از کجا شروع کنم. آن روز یاد گرفتم که Pull Request یک کار اداری نیست؛ یک قرارداد فنی بین نویسنده و بازبین است که اگر درست طراحی نشود، فرآیند توسعه را کندتر از آن می‌کند که سرعت می‌بخشد. اگر تازه با Git آشنا می‌شوید، آموزش Git از صفر نقطه شروع خوبی است و برای مرور پایه‌ها، GitHub در ویکی‌پدیا مفید است.

Pull Request دقیقاً چیست و چه فرقی با merge دارد؟

Pull Request که به اختصار PR گفته می‌شود، یک درخواست برای ادغام تغییرات از یک شاخه به شاخه دیگر است. اما تفاوت مهم PR با merge خالص در این است که PR یک فضای گفت‌وگو می‌سازد: بازبین می‌تواند خط به خط کد را کامنت کند، نویسنده می‌تواند پاسخ دهد، CI می‌تواند تست‌ها را اجرا کند و تاریخچه گفت‌وگو برای آینده باقی بماند. این ویژگی، PR را به ابزاری آموزشی و مستندساز تبدیل می‌کند.

در پروژه‌های واقعی، PR سه کارکرد اصلی دارد. اول، به‌عنوان دروازه کیفیت: هیچ کدی بدون بازبینی به شاخه اصلی نمی‌رسد. دوم، به‌عنوان سند یادگیری: کامنت‌ها و تصمیم‌ها در PR باقی می‌مانند و می‌توانند برای تصمیم‌های بعدی مرجع باشند. سوم، به‌عنوان چرخه بازخورد سریع: نویسنده زودتر از انتشار به production بازخورد می‌گیرد و هزینه اصلاح کمتر است. برای درک بهتر شاخه‌ها در Git، برنچ در Git راهنمای کاملی دارد.

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

آناتومی یک Pull Request حرفه‌ای

یک PR حرفه‌ای، پنج بخش اصلی دارد که هرکدام هدف مشخصی را دنبال می‌کند:

  • عنوان مشخص: در یک نگاه بگوید چه کاری انجام می‌شود، مثل Add payment gateway for Zarinpal.
  • توضیحات: زمینه تغییر، دلیلی که این تغییر لازم شد و راه‌حل انتخاب‌شده.
  • فهرست تست: چه چیزهایی تست شده و چطور می‌توان تکرار کرد.
  • اسکرین‌شات یا ویدئو: برای تغییرات UI، حیاتی است.
  • لینک به issue: اگر مرتبط با issue مشخصی است، آن را لینک کنید تا زمینه بحث روشن باشد.

الگوی حرفه‌ای که در تیم‌ها توصیه می‌کنم، قالبی است که در خود GitHub تنظیم می‌شود: یک فایل pull_request_template.md در پوشه .github که به صورت خودکار، متن پیش‌فرض PR را تنظیم می‌کند. این کار باعث می‌شود همه PRها ساختار یکسان داشته باشند و بازبین سریع‌تر بتواند تصمیم بگیرد. برای مدیریت پروژه در GitHub، مدیریت پروژه با GitHub Projects نکات کاربردی دارد.

اندازه PR: چرا کوچک‌تر بهتر است

تجربه‌ای که در ده‌ها پروژه تکرار شده: PRهای بزرگ دیرتر بازبینی می‌شوند، باگ بیشتری دارند و اغلب با تأیید سطحی ادغام می‌شوند. قاعده‌ای که در تیم‌ها به آن رسیدم: هر PR باید کمتر از ۴۰۰ خط تغییر باشد و اگر بیشتر شد، به چند PR شکسته شود. این عدد از تجربه است، نه از کتاب. مرز واقعی این است که بازبین بتواند در یک نشست کاری، کل تغییر را با دقت بخواند.

حجم PRزمان بازبینی معمولریسک ورود باگ
زیر ۱۰۰ خطچند دقیقهکم
۱۰۰ تا ۴۰۰ خطیک نشستمتوسط
۴۰۰ تا ۱۰۰۰ خطچند روزبالا
بالای ۱۰۰۰ خطهفته‌ها یا بی‌بازبینیبسیار بالا

روش شکستن PR بزرگ به PRهای کوچک: ابتدا تغییرات زیرساختی یا بازنویسی‌های خالص، بعد قابلیت‌های جدید، و در آخر اصلاحات ظاهری. اگر به این ترتیب پیش بروید، هر PR یک هدف مشخص دارد و بازبینی ساده‌تر می‌شود. برای اصول کدنویسی تمیز که این تفکیک را ساده‌تر می‌کند، اصول کدنویسی تمیز در پروژه‌های وردپرس را ببینید.

فرآیند بازبینی موثر

بازبینی موثر، یک مهارت است که تمرین می‌خواهد. چند اصولی که در تیم‌ها به آن رسیدم:

  • بازبین مشخص: هر PR باید یک یا دو بازبین داشته باشد، نه صفر و نه پنج. بازبین‌های زیاد باعث می‌شود هیچ‌کس خودش را مسئول نداند.
  • زمان پاسخ مشخص: در تیم‌ها معمولاً توافق می‌کنیم که هر PR در ۲۴ ساعت کاری بازبینی شود. انتظار طولانی، انگیزه نویسنده را می‌کشد.
  • کامنت‌های سازنده: به جای «این غلط است»، بنویسید «این خط ممکن است در حالت فلان باگ بزند، چون...». کامنت باید یاد بدهد، نه سرزنش کند.
  • تفکیک نظر و شرط: نظر شخصی را به‌عنوان «ممکن است بهتر باشد» و شرط فنی را به‌عنوان «این باید اصلاح شود» بنویسید تا نویسنده بداند کدام اجباری است.
  • تأیید سریع: وقتی PR آماده است، تأیید سریع، چرخه بازخورد را کوتاه می‌کند. تردید طولانی، ارزش PR را کاهش می‌دهد.

در تیم‌های تازه‌شکل‌گرفته، توصیه می‌کنم یک برچسب برای PRها تعریف کنید: ready for review، needs changes، approved. این برچسب‌ها، وضعیت PR را در یک نگاه روشن می‌کنند. برای مدیریت کامل مخزن، تجربه استفاده از GitHub در پروژه‌های تیمی نکات ارزشمندی دارد.

یک نکته ظریف در بازبینی که در پروژه‌ها زیاد دیدم: برای تغییرات بزرگ، اول یک نشست شفاهی با نویسنده بگیرید و در آن کلیات را بررسی کنید. بعد کامنت‌های فنی را در PR بنویسید. این کار جلوی رفت‌وبرگشت‌های طولانی در متن را می‌گیرد و تصمیم‌گیری سریع‌تر می‌شود.

ادغام با CI/CD و تست خودکار

هر PR باید حداقل یک تست خودکار داشته باشد که قبل از ادغام پاس شود. بدون این لایه، کیفیت بازبینی کاملاً به دقت انسانی وابسته است و در تیم‌های پرمشغله، این ضعیف‌ترین حلقه است. GitHub Actions ابزار استاندارد برای این کار است و راهنمای کاملش در GitHub Actions آمده است. برای CI/CD در پروژه‌های وردپرسی، CI/CD برای پروژه‌های وردپرسی راهنمای عملی دارد.

چند تست که در همه PRها توصیه می‌شود: تست‌های واحد برای منطق دامنه، تست‌های integration برای مسیرهای اصلی و lint برای بررسی سبک کد. اگر پروژه وردپرسی است، یک تست ساده که روی نسخه استیجینگ، اتصال به دیتابیس و بارگذاری سایت را چک کند، بسیاری از باگ‌های بدیهی را قبل از production می‌گیرد. برای تست و دیباگ پروژه‌های وردپرسی، تست و دیباگ پروژه‌های وردپرس راهنمای کاملی دارد.

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

مدیریت تعارض در Pull Request

تعارض زمانی رخ می‌دهد که شاخه شما و شاخه اصلی، یک بخش از کد را متفاوت تغییر داده باشند. در این حالت، GitHub پیامی نشان می‌دهد که «This branch has conflicts that must be resolved». راهنمای کامل در حل تعارض در Git آمده است. چند نکته از تجربه:

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

یک عادت که در تیم‌ها تعارض را کاهش می‌دهد: هر روز صبح، شاخه شخصی را با main همگام کنید. این کار باعث می‌شود تعارض‌ها کوچک بمانند و در مرحله نهایی PR، کار بازبینی ساده‌تر شود. برای مدیریت شاخه‌ها در Git، برنچ در Git راهنمای کاربردی دارد.

اشتباهات رایج در استفاده از PR

چند اشتباه که در پروژه‌های مختلف دیده‌ام:

  • PR بدون توضیحات: بازبین باید حدس بزند هدف تغییر چیست. این کار زمان بازبینی را دو برابر می‌کند.
  • PRهای زامبی: PRی که هفته‌ها باز است و به آن رسیدگی نمی‌شود. یا باید سریع بازبینی شود یا بسته شود.
  • ادغام بدون تأیید: اگر فرآیند بازبینی در تیم جدی نیست، PR به یک مرحله تشریفاتی تبدیل می‌شود.
  • افزودن کامیت‌های بی‌ربط: PR باید فقط شامل تغییرات مرتبط با هدفش باشد. تغییرات جانبی را در PRهای جدا بگذارید.
  • بازبینی سطحی: اگر بازبین فقط یک نگاه به کد بیندازد و تأیید کند، PR به ابزار کیفیت تبدیل نمی‌شود.

اگر با خطاهای رایج Git مواجه شدید، رفع خطاهای رایج Git راهنمای کاملی دارد. برای مدیریت بهتر پروژه‌های تیمی، Jira برای مدیریت پروژه توسعه و Notion برای مدیریت پروژه نکات مفیدی دارند.

هر PR یک قرارداد است، نه یک درخواست. نویسنده متعهد می‌شود تغییرات قابل‌بازبینی و قابل‌دفاع بفرستد؛ بازبین متعهد می‌شود بازخورد دقیق و سازنده بدهد.

پرسش‌های پرتکرار درباره Pull Request

تفاوت Pull Request و Push چیست؟ Push ارسال کامیت‌ها به مخزن راه دور است. Pull Request درخواست ادغام یک شاخه به شاخه دیگر. Push پیش‌نیاز PR است اما PR مرحله بعدی و مهم‌تر است.

چند بازبین برای یک PR مناسب است؟ معمولاً یک یا دو بازبین. برای تغییرات حساس، دو بازبین توصیه می‌شود. اما بازبین‌های بیش از حد، سرعت بازبینی را کاهش می‌دهد.

آیا می‌توانم بعد از ارسال PR، کامیت جدید اضافه کنم؟ بله. کامیت‌های جدید به PR اضافه می‌شوند. اگر می‌خواهید تاریخچه PR تمیز بماند، قبل از ادغام نهایی می‌توانید از squash استفاده کنید.

تفاوت squash، merge و rebase در ادغام PR چیست؟ squash همه کامیت‌های PR را در یک کامیت ادغام می‌کند، merge با حفظ تاریخچه و rebase بدون کامیت merge اضافی. هرکدام در سناریوهای متفاوتی مناسب هستند.

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

برای سایر موضوعات Git، آموزش Git از صفر، دستورات ضروری Git و برنچ در Git را ببینید. برای کار با GitLab، GitLab برای تیم‌های DevOps و مهاجرت از GitHub به GitLab راهنمای کاربردی دارند. برای پروژه‌های وردپرسی که با Git مدیریت می‌شوند، گیت در توسعه وردپرس نکات ارزشمندی دارد. اگر با مدیریت پروژه کار می‌کنید، مدیریت پروژه با GitHub Projects و مقایسه Asana و Monday را ببینید.

آنچه از پروژه‌های تیمی یاد گرفتم

سه چیز بعد از سال‌ها کار با Pull Request در تیم‌های مختلف یاد گرفتم. اول، PRهای کوچک از هر بهینه‌سازی دیگری موثرترند. دوم، بازبینی سازنده مهم‌تر از سرعت بازبینی است. سوم، PR یک فرآیند است نه یک اتفاق؛ برای اینکه درست کار کند، باید در فرهنگ تیم جا بیفتد. برای اصول کار تیمی، تجربه‌های تیمی در پروژه‌های وردپرسی نکات ارزشمندی دارد. برای ساختار پروژه، ساختاربندی پروژه توسعه وردپرس و اصول کدنویسی تمیز را ببینید. برای مدیریت زمان، مدیریت زمان در فریلنسری راهنمای کاربردی ارائه می‌دهد.

اگر تجربه‌ای از یک Pull Request که کیفیت کد را تغییر داد یا برعکس، PRی که باعث سردرگمی شد، دارید، در دیدگاه بنویسید. برای من جالب است بدانم کدام بخش از فرآیند PR در تیم شما بهترین نتیجه را داده است. 🔀