Pull Request چیست؟ پیشنهاد ادغام با Review قبل از ورود به main

Merge محلی تاریخچه را عوض می‌کند؛ Pull Request (PR) روی GitHub یک گفت‌وگوی ساخت‌یافته دور همان پیشنهاد ادغام است: diff، کامنت، CI، و مجوز Merge. مسئله‌ای که حل می‌کند این است که تغییر قبل از رسیدن به main دیده، تست و مستند شود — نه اینکه فقط روی ماشین یک نفر git merge بخورد.

مقالهٔ ۰۷۸ تفاوت نام PR و Merge Request را گفت؛ اینجا عمق فرآیند: PR چه هست، چه نیست، Draft، اندازهٔ خوب، و پیوند با Branch protection. خودِ Git فرمان «pull request» ندارد؛ این لایهٔ هاست است.

پاسخ کوتاه

طبق GitHub Docs، Pull Request به دیگران اعلام می‌کند که یک Branch تغییراتی دارد و می‌خواهید آن‌ها را وارد Branch دیگری (معمولاً main) کنید. در صفحهٔ PR می‌توانید diff را دید، بحث کرد، Commit جدید Push کرد و در نهایت با یکی از روش‌های merge/squash/rebase ادغام کرد — اگر چک‌ها و Review لازم برقرار باشند.

PR واحد تحویل تغییر در تیم مدرن است: کد + زمینه + شواهد CI، نه فقط فایل‌های عوض‌شده.

چه مسئله‌ای را در تیم حل می‌کند؟

• بازبینی قبل از ورود به خط پایدار.
• ردپای تصمیم‌ها در کامنت‌ها برای نفر بعدی.
• اتصال به Issue، طراحی و چک‌لیست.
• اجرای خودکار تست روی هر Push به Branch PR.
• کنترل دسترسی: همه Push به main ندارند، ولی می‌توانند PR باز کنند.

بدون PR، یا همه به main دسترسی مستقیم دارند (ریسک)، یا گلوگاه «لید خودش Merge می‌کند بدون زمینه».

آناتومی یک PR خوب

1. عنوان روشن که منظور را بگوید.
2. بدنه: چرا، چگونه تست شد، ریسک، اسکرین/لینک Issue.
3. اندازهٔ بازبینی‌پذیر؛ در صورت لزوم چند PR.
4. Branch به‌روز نسبت به پایه برای Conflict کمتر.
5. CI سبز و پاسخ به کامنت‌های Blocking.

Draft PR اعلام می‌کند «هنوز برای Review نهایی نیامده» ولی می‌تواند بازخورد زودهنگام بگیرد. Ready for review وقتی است که نویسنده واقعاً وقت Reviewer را می‌خواهد.

جدول: PR در برابر فقط Push به main

جریان کاری نمونه

bash

git switch -c feature/paywall # ... commits ... git push -u origin feature/paywall # سپس در GitHub: Compare & pull request

بعد از باز شدن PR: Review (۲۰۹)، رفع کامنت با Commitهای جدید، حل Conflict اگر لازم، و Merge طبق سیاست مخزن. حذف Branch بعد از Merge بهداشت است.

اندازه و دامنه: مشکل PR غول‌پیکر

PR هزارخطی با پنج موضوع قاطی Review را سطحی می‌کند. بهتر است: جدا کردن refactor مکانیکی از تغییر رفتاری، و توضیح در بدنه اگر جداسازی ممکن نیست. Squash در پایان تاریخچهٔ main را خلوت می‌کند ولی Review روی Commitهای میانی هم می‌تواند مفید باشد — قرارداد تیم.

اشتباه‌های رایج

• عنوان «fix» بدون زمینه.
• PR بی‌توضیح با اتکا به اینکه «diff خودش معلوم است».
• درخواست Review وقتی هنوز WIP شکسته است بدون Draft.
• نادیده گرفتن CI قرمز و اصرار به Merge.
• باز نگه داشتن PR هفته‌ها بدون همگام‌سازی با main.

PR به‌عنوان واحد ارتباطی با غیرمهندس

مدیر محصول یا امنیت ممکن است کد نخواند، ولی عنوان، چک‌لیست ریسک، و لینک Issue در PR برایشان قابل‌پیگیری است. PR خوب ترجمهٔ کار فنی به تصمیم قابل‌فهم است. وضعیت «Blocked on review» یا «Waiting on QA» را در برچسب‌ها شفاف کنید تا صف مبهم نشود.

قالب پیشنهادی بدنهٔ PR

markdown

## خلاصه - چه مشکلی حل می‌شود؟ ## نحوهٔ تست - [ ] واحد - [ ] دستی در staging ## ریسک - مهاجرت؟ کش؟ سازگاری API؟ ## تصاویر / لینک - Issue #123

مخازن می‌توانند این قالب را با Pull request template در GitHub اجباری کنند تا نویسنده زمینه را خالی نگذارد.

بستن حلقه بعد از Merge

• حذف Branch فرعی در UI یا محلی.
• تأیید Deploy روی Commit/PR مشخص.
• بروزرسانی Issue و changelog اگر لازم است.
• یادداشت برای PRهای داغ که Conflict بعدی نسازند (مثلاً اطلاع به Branchهای موازی).

برچسب‌ها، Milestone و اتصال Issue

برچسب‌هایی مثل bug، security، needs-design صف را قابل فیلتر می‌کنند. بستن خودکار Issue با واژه‌های Fixes #id در بدنهٔ PR ردیابی را کامل می‌کند. بدون این‌ها، PRها به جزایر بدون زمینه تبدیل می‌شوند.

حقوق دسترسی: چه کسی Merge می‌کند؟

مدل رایج: نویسنده Merge نمی‌کند تا حداقل یک Approve بیاید؛ یا نویسنده بعد از Approve می‌تواند Merge کند. انتخاب به فرهنگ تیم بستگی دارد. مهم این است که Bypass عمدی Branch protection نادر و حساب‌شده باشد — وگرنه PR نمایشی می‌شود.

PR و محیط‌های Preview

بسیاری تیم‌ها برای هر PR یک محیط موقت می‌سازند تا QA بدون Merge به main تست کند. این لایه روی مفهوم PR سوار است: واحد پیشنهاد تغییر باید قابل اشاره و Deploy موقت باشد. اگر Preview ندارید، حداقل دستور تست دستی را در بدنه بنویسید.

ضدالگوهای صف PR

• PRهای وابستهٔ زنجیره‌ای بدون توضیح که Reviewer ترتیب را نفهمد.
• باز کردن PR فقط برای «جای پارک» کد بدون Draft.
• Merge شنبه شب بدون حضور نویسنده برای Rollback.
• PRهایی که نیمه‌کاره CI را قرمز نگه می‌دارند و نویز می‌سازند.

بهداشت صف به اندازهٔ کیفیت یک diff مهم است؛ لید باید صف را مثل بکاپ محصول ببیند.

سوالات متداول

PR همان git pull است؟

خیر. git pull همگام‌سازی محلی با Remote است. Pull Request پیشنهاد ادغام روی هاست با لایهٔ اجتماعی و CI است.

آیا برای پروژهٔ یک‌نفره لازم است؟

اجباری نه؛ ولی برای فعال کردن CI روی هر تغییر و عادت آینده مفید است. بعضی تنها کارها هم از PR استفاده می‌کنند.

Fork و PR

در متن‌باز معمولاً از Fork به مخزن بالادست PR می‌دهید. در تیم داخلی اغلب Branch روی همان مخزن کافی است.

خلاصه

Pull Request سازوکار پیشنهاد ادغام همراه Review، بحث و چک خودکار است. مسئله‌اش کیفیت ورود به main است نه جایگزین Git. PR خوب کوچک، توضیح‌دار و تست‌شده است؛ دکمهٔ Merge فقط پایان فرآیند است.

قدم بعد: خودِ Code Review روی GitHub (۲۰۹) و سیاست‌های Branch protection (۲۲۰).

منابع و مراجع

• GitHub Docs — About pull requests — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
• GitHub Docs — Creating a pull request — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
• GitHub Docs — About pull request merges — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges
• GitHub Docs — About draft pull requests — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests#draft-pull-requests
• GitHub Flow guide — https://docs.github.com/en/get-started/using-github/github-flow