Code Review در GitHub چگونه انجام می‌شود؟ از کامنت تا Approve

Code Review روی GitHub عمدتاً روی Pull Request زندگی می‌کند: خواندن diff، گذاشتن کامنت خطی، و ثبت Review با یکی از حالت‌های Comment، Approve یا Request changes. مسئله فقط پیدا کردن باگ نیست؛ کاهش ریسک تولید، انتقال دانش، و یکدست‌کردن استاندارد تیم است. مقالهٔ ۰۷۹ مفهوم عمومی Review را گفت؛ اینجا زاویهٔ عملی روی GitHub و آسیب‌شناسی Review بد.

مستندات GitHub About pull request reviews این حالت‌ها و پیشنهاد تغییر را شرح می‌دهد. Branch protection می‌تواند حداقل یک Approve را اجباری کند تا دکمهٔ Merge بدون بازبینی کار نکند.

پاسخ کوتاه

Reviewer فایل‌های عوض‌شده را می‌بیند، روی خطوط مشخص کامنت می‌گذارد، در صورت نیاز Suggested change پیشنهاد می‌کند، و در پایان Review را Submit می‌کند. Approve به‌معنی رضایت از ادغام (با فرض سبز بودن CI) است؛ Request changes مانع ادغام در مخازن با قوانین سخت می‌شود تا اصلاحات بیاید. Comment بازخورد بدون قفل کردن است.

Review خوب دربارهٔ تغییر است نه شخصیت نویسنده؛ لحن تند دانش را متوقف می‌کند.

هدف‌های Review — اولویت‌بندی

1. صحت و امنیت: منطق غلط، تزریق، نشت Secret، مجوز نادرست.
2. رگرسیون و سازگاری با قراردادهای موجود.
3. خوانایی و قابلیت نگهداری در محدودهٔ معقول.
4. اشتراک دانش و پرسش‌های آموزشی.

اگر همه چیز را در یک PR به سطح ایده‌آل معماری برسانید، صف Review می‌میرد. اولویت ریسک تولید است؛ پیشنهادهای سبک را به‌صورت non-blocking علامت بزنید.

ابزارهای GitHub که باید بشناسید

• کامنت خطی و شروع Review چندکامنتی قبل از Submit.
• Suggested changes برای اصلاح کوچک قابل یک‌کلیک.
• Files changed / Commits برای دیدن دامنه.
• CODEOWNERS برای Reviewer اجباری حوزه.
• Required reviews در Branch protection.

CI و botها مکمل‌اند نه جایگزین انسان برای تصمیم محصولی و تهدیدهای منطقی پیچیده.

چک‌لیست Reviewer

چک‌لیست نویسنده قبل از درخواست Review

• خودتان یک‌بار diff را مثل Reviewer بخوانید.
• بدنهٔ PR زمینه و نحوهٔ تست را بگوید.
• CI محلی/ریموت سبز باشد یا علت قرمز معلوم باشد.
• PR را با دامنهٔ یک منظور نگه دارید.
• به کامنت‌ها پاسخ دهید: Fixed / Won’t fix با دلیل.

فرهنگ: Review سمی در برابر مؤثر

مؤثر: مشخص، قابل اقدام، با اشاره به ریسک. سمی: تمسخر، بازنویسی سلیقه‌ای کل فایل بدون معیار، یا Approve بدون خواندن. تیم‌های سالم زمان Review را در ظرفیت Sprint حساب می‌کنند؛ Review رایگان و آنی نیست.

برای تغییرهای حساس (امنیت، پرداخت، داده) دو Reviewer یا الزام CODEOWNERS منطقی است. برای typo در docs، یک Approve سبک کافی است.

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

1. Approve برای «دوستانه بودن» بدون خواندن.
2. ده‌ها nit بدون تفکیک Blocking.
3. بحث طولانی در کامنت که باید به طراحی/Issue برود.
4. نادیده گرفتن پیشنهاد امنیتی به‌خاطر عجلهٔ Release.
5. Review فقط روی آخرین Commit و از دست دادن زمینهٔ کل PR.

نمونهٔ کامنت قابل اقدام در برابر مبهم

مبهم: «این خوب نیست.» قابل اقدام: «این شاخه در صورت null بودن user، 500 برمی‌گرداند؛ در خط ۲۸ یا زودتر 400 برگردانید تا با قرارداد API در docs/errors.md یکی شود.» دومی هم مشکل را می‌گوید هم مسیر اصلاح را.

برای نیت‌های سبک از پیشوندهایی مثل nit: استفاده کنید تا نویسنده بداند Blocking نیست. برای امنیت هرگز nit نگذارید.

Review در حضور CI و ربات

اگر ربات استایل را چک می‌کند، وقت انسان را روی همان خرج نکنید مگر ربات غلط می‌گوید. تمرکز انسان: مرز دامنه، تهدید، خوانایی قراردادهای دامنه، و تست‌های غایب. Approve وقتی CI قرمز است فقط با توضیح صریح معنا دارد؛ وگرنه سیگنال را خراب می‌کنید.

زمان‌بندی و ظرفیت

Review کار واقعی است. اگر همه فقط صبح‌ها کد می‌نویسند و عصرها صف PR می‌ترکد، SLO نقض می‌شود. چرخش Reviewer، محدود کردن اندازهٔ PR، و اختصاص زمان تقویمی برای Review بخشی از طراحی فرآیند است نه اخلاق فردی صرف.

Suggested changes و Commit از Review

پیشنهاد خطی GitHub برای اصلاحات کوچک عالی است؛ برای بازطراحی بزرگ بهتر است کامنت توضیحی بگذارید تا نویسنده خودش Commit بزند. دسته کردن پیشنهادها در یک Review به‌جای ده اعلان جدا، نویز را کم می‌کند.

Review بعد از Push جدید

وقتی نویسنده Commit جدید می‌آورد، Review قبلی ممکن است stale شود. عادت خوب: روی تغییرات جدید یک Review تازه یا حداقل تأیید «لینت‌ها را دیدم». در مخازن با dismiss stale reviews، Approve قدیمی خودکار کنار می‌رود — این را به تیم توضیح دهید تا غافلگیر نشوند.

Review امنیتی حداقلی

حتی در تیم بدون Security Engineer، Reviewer می‌تواند بپرسد: آیا ورودی اعتبارسنجی شده؟ آیا Secret در diff هست؟ آیا مجوز دسترسی درست است؟ آیا لاگ دادهٔ حساس می‌نویسد؟ این چک‌لیست کوتاه جلوی کلاس بزرگی از حوادث را می‌گیرد و با مقالهٔ ۲۱۶–۲۱۷ هم‌مسیر است.

آمار بدون وسواس

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

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

چقدر طول بکشد؟

به اندازهٔ PR بستگی دارد. SLA تیمی (مثلاً یک روز کاری برای PR متوسط) بهتر از انتظار مبهم است.

آیا AI جای Reviewer را می‌گیرد؟

می‌تواند الگو و اشتباه سطحی را علامت بزند؛ مسئولیت ادغام و فهم دامنه هنوز با انسان و سیاست تیم است. مقالهٔ ۱۳۰ همین سری به AI code review می‌پردازد.

Request changes را کی بردارم؟

وقتی نویسنده اصلاحات را Push کرد، Review جدید ثبت کنید (Approve یا Comment). رها کردن Request changes کهنه صف را قفل می‌کند.

خلاصه

Code Review روی GitHub لایهٔ انسانی کیفیت قبل از Merge است: کامنت خطی، حالت‌های Review، و قوانین مخزن. هدف کاهش ریسک و اشتراک دانش است با لحن قابل اقدام. نویسنده با PR تمیز و Reviewer با اولویت‌بندی ریسک، جریان را زنده نگه می‌دارند.

پیوندها: ۲۰۸ برای خود PR، ۲۲۰ برای اجباری کردن Review، ۱۳۰ برای نقش AI.

منابع و مراجع

• GitHub Docs — About pull request reviews — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews
• GitHub Docs — Reviewing proposed changes in a pull request — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request
• GitHub Docs — Approving a pull request with required reviews — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/approving-a-pull-request-with-required-reviews
• GitHub Docs — About code owners — https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
• GitHub Docs — Commenting on a pull request — https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request