پُل ریکویست: چیستؘ فرآیند ایجاد و کد ریویو

Pull Request چیست؟

Pull Request (PR) — یک درخواست رسمی برای انطباق تغییرات از یک شاخه به شاخه دیگر در چارچوب یک سیستم کنترل نسخه توزیع‌شده است. PR عنصر مرکزی توسعه مشترک در پلتفرم‌های GitHub، GitLab و Bitbucket است و بحث کد، آزمایش خودکار و فرآیند تایید تغییرات را ترکیب می‌کند.

نام «Pull Request» ماهیت عملیات را منعکس می‌کند: توسعه‌دهنده از صاحب مخزن می‌خواهد (request) تغییراتش را بگیرد (pull). این اصطلاح در سال 2008 توسط GitHub معرفی شد — قبل از آن مکانیسم مشابهی به صورت پاتچ و merge request (اصطلاح GitLab) وجود داشت. امروزه PR استاندارد دو فاکتو برای کار گروهی با Git است.

به گزارش GitHub Octoverse, 2025، 89% پروژه‌های منبع‌باز برای ایجاد تغییرات نیازمند ایجاد PR هستند. در توسعه شرکتی این شاخص به 95% می‌رسد. PR نه تنها یک ابزار فنی، بلکه بخشی از فرهنگ توسعه شده است: از طریق PR انتقال دانش، کشف باگ‌ها و توافق در مورد تصمیمات معماری انجام می‌شود.

اجزای Pull Request

یک PR تیپیکی شامل عنوان، توصیف، فهرست فایل‌های تغییریافته (diff)، نظرات بازبین‌ها و وضعیت بررسی‌های CI است. هر PR به شاخه مبدا و هدف مشخصی متصل است و پس از ادغام می‌تواند به طور خودکار حذف شود.

چگونه Pull Request ایجاد کنیم

ایجاد PR با انتشار شاخه feature در مخزن دور آغاز می‌شود. پس از push، توسعه‌دهنده PR را از طریق رابط پلتفرم یا CLI (gh، glab) باز می‌کند. فرآیند را با مثال GitHub بررسی می‌کنیم.

Push شاخه و باز کردن PR

گام اول — شاخه feature را به مخزن دور push کرده و از طریق رابط وب یا خط فرمان Pull Request ایجاد کنید.

# شاخه feature را ایجاد و push کنید
git checkout -b feature/biometric-auth
git add src/auth/
git commit -m "feat: add biometric authentication"
git push -u origin feature/biometric-auth

# از طریق GitHub CLI PR ایجاد کنید
gh pr create --title "feat: add biometric authentication" \
  --body "Implements fingerprint and face recognition login.
  Closes #142" \
  --base develop

پس از ایجاد PR، GitHub به طور خودکار خط لوله CI (GitHub Actions) را اجرا، وجود تعارض با شاخه هدف را بررسی و بازبین‌ها را دعوت می‌کند. قالب توصیف PR را می‌توان از طریق .github/PULL_REQUEST_TEMPLATE.md پیکربندی کرد تا تمامی PR‌ها شامل بخش‌های اجباری باشند: هدف، تغییرات، آزمایش، وظایف مرتبط.

توصیف و برچسب‌گذاری

توصیف کیفی PR شامل: لینک به وظیفه (issue/ticket)، توصیف کوتاه تغییرات، دستور آزمایش و فهرست تغییرات مرتبط. برچسب‌ها (bug، feature، refactoring) به دسته‌بندی PR کمک می‌کنند، و تکلیف‌شوندگان و بازبین‌ها به طور خودکار از طریق CODEOWNERS تعیین می‌شوند.

# بازبین‌ها را از طریق CODEOWNERS تعیین کنید (فایل در ریشه مخزن)
# مثال .github/CODEOWNERS:
# src/auth/ @team-auth @senior-dev
# src/api/ @team-backend
# *.kt @kotlin-team

# ایجاد PR با تعیین بازبین از طریق gh cli
gh pr create --reviewer "team-auth" --label "feature"

CODEOWNERS — یک مکانیسم استاندارد GitHub/GitLab برای تعیین خودکار بازبین‌ها بر اساس فایل‌های تغییریافته است. به عنوان مثال، هر تغییری در شاخه src/auth/ به طور خودکار team-auth و senior-dev را به عنوان بازبین تعیین می‌کند. این فرآیند را سریع می‌کند و تضمین می‌کند که افراد مورد نیاز PR را مشاهده کنند.

به‌روزرسانی PR پس از بازبینی

پس از دریافت نظرات بازبین، توسعه‌دهنده در همان شاخه feature تصحیحات را اعمال کرده و commit‌های جدید را push می‌کند — PR به طور خودکار به‌روز می‌شود. مهم است تاریخچه (rebase) را در شاخه feature منتشرشده بازنویسی نکنید اگر PR قبلاً باز شده است، زیرا این کار لینک‌های commit‌های مشخص را در نظرات می‌شکند.

# طبق نظرات بازبین تغییرات اعمال کنید
git checkout feature/biometric-auth
# کد را تصحیح کنید
git commit -m "fix: handle biometric timeout per review"
git push

# PR به طور خودکار به‌روز می‌شود
# پس از تایید، PR را از طریق رابط GitHub ادغام کنید

فرآیند کد ریویو

کد ریویو — عنصر مرکزی Pull Request است. بازبین تغییرات را از نظر صحت، سبک کد، امنیت و تطابق معماری بررسی می‌کند. یک کد ریویو کیفی نه تنها از باگ‌ها جلوگیری می‌کند، بلکه دانش را درباره پایگاه کد در داخل تیم پخش می‌کند.

Google Engineering Practices (2025) اصول زیر کد ریویو را توصیه می‌کند: بازبین باید زمینه تغییرات را درک کند، به جای ایرادات کلی توصیه‌های مشخص دهد، و نظرات فنی و سبکی را از هم جدا کند. زمان کد ریویو نباید از 24 ساعت پس از ایجاد PR تجاوز کند.

برای توسعه اپلیکیشن موبایل، کد ریویو شامل بررسی‌های مخصوصی است: بررسی سازگاری با targetSdk، صحت پردازش lifecycle (Android) / view lifecycle (iOS)، نبود نشت حافظه (LeakCanary، Instruments)، پشتیبانی از حالت تاریک و محلی‌سازی. این بررسی‌ها را می‌توان از طریق لینترها و Detekt/ktlint خودکار کرد.

انواع نظرات

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

پس از حل شدن تمامی نظرات و پس از انجام بررسی‌های CI، بازبین تایید (Approved) را ارسال می‌کند. PR می‌تواند ادغام شود. GitHub و GitLab از قوانین حفاظت شاخه (branch protection rules) پشتیبانی می‌کنند: تعداد اجباری تاییدها، بررسی‌های اجباری CI، ممنوعیت push به main بدون PR. برای پروژه‌های موبایل، branch protection همچنین بررسی build را هم شامل می‌شود: اگر اپلیکیشن ساخته نشود (gradle build failed / xcodebuild failed)، PR نمی‌تواند ادغام شود.

حل تعارض در PR

تعارضات merge در Pull Request وضعیتی عادی در کار گروهی فعال است. پلتفرم‌ها برای تعارضات ساده حل از طریق رابط وب ارائه می‌دهند یا توصیه به حل محلی می‌کنند. GitHub Actions به طور خودکار قابلیت ادغام را در هر push به شاخه feature بررسی کرده و PR را به عنوان conflict علامت می‌زند اگر ادغام ممکن نباشد.

بهترین روش‌های Pull Request

Pull Request‌های مؤثر کد ریویو را سریع کرده و تعداد باگ‌ها را کاهش می‌دهند. تحقیق SmartBear (2025) نشان داد که PR‌های تا 200 خط کد 2 برابر بیشتر نظر مفید دریافت می‌کنند نسبت به PR‌های با بیش از 1000 خط، و زمان کد ریویو 3 برابر کاهش می‌یابد.

• PR‌های کوچک — اندازه بهینه 100-300 خط. PR‌های بزرگ را به بخش‌های منطقی تقسیم کنید: هر PR یک وظیفه را حل می‌کند. این کد ریویو را ساده کرده و احتمال تعارض را کاهش می‌دهد
• توصیف واضح — عنوان مطابق Conventional Commits (feat:, fix:, refactor:)، متن PR شامل «چه و چرا» است نه «چگونه» (کد خود گویا است). قالب: هدف → تغییرات → آزمایش → مسائل مرتبط
• بازخورد سریع — کد ریویو طی 24 ساعت. اگر PR بیشتر از یک روز صبر کند — تیم زمینه را از دست می‌دهد، تعداد تعارضات در ادغام افزایش می‌یابد
• خودکارسازی — لینترها، فرمات‌دهنده‌ها و آزمون‌ها باید به طور خودکار با ایجاد PR اجرا شوند. اجازه ادغام PR با بررسی‌های CI قرمز را ندهید
• Draft PR — برای بحث اولیه درباره معماری استفاده کنید. Draft PR نیازی به کد ریویو ندارد و نمی‌تواند ادغام شود، اما به شما امکان نشان دادن کد را در مرحله اولیه می‌دهد

روش‌های اضافی: شب جمعه PR ایجاد نکنید (هیچ کس تا دوشنبه کد ریویو نمی‌کند)، از 1-2 نفر کد ریویو بخواهید (بیشتر فرآیند را بدون افزایش کیفیت کند می‌کند)، از squash merge برای فشرده سازی تاریخچه قبل از ادغام استفاده کنید. برای پروژه‌های موبایل توصیه می‌شود در توصیف PR لینک build تستی (Firebase App Distribution / TestFlight) را اضافه کنید تا بازبین بتواند تغییرات را در یک اپلیکیشن عملکنده بررسی کند.

Pull Request در پلتفرم‌های مختلف

پلتفرم‌های اصلی برای کار با Pull Request — GitHub، GitLab و Bitbucket هستند. علیرغم مفهوم مشترک، هر کدام D88خصوصیاتی دارد که در انتخاب ابزار برای تیم باید مد نظر قرار گیرد.

GitHub — محبوبترین پلتفرم با بزرگترین جامعه، Actions برای CI/CD و اکوسیستم گسترده اپلیکیشن (GitHub Marketplace). GitLab با CI/CD توکاره و قابلیت استقرار کامل self-hosted متمایز می‌شود. Bitbucket با Jira و اکوسیستم Atlassian ادغام شده است و در محیط‌های شرکتی محبوب است.

برای توسعه اپلیکیشن موبایل انتخاب پلتفرم غالباً توسط قابلیت‌های CI/CD تعیین می‌شود: GitHub Actions از macOS runners برای ساخت iOS پشتیبانی می‌کند، GitLab runners توکاره برای iOS/Android دارد، Bitbucket با Firebase Test Lab خوب انتگرال می‌شود. بدون توجه به پلتفرم، فرآیند PR یکسان است: شاخه → review → CI → merge.