راهنمای Pull Request نگه‌دارندگان

به عنوان نگهدارنده، بررسی Pull Requestها کاری است که نسبتاً منظم انجام می‌دهید. این سند شامل چند راهنمای بررسی Pull Request مخصوص Exercism است.

بررسی Pull Requestهای تمرین

بررسی Pull Request یک تمرین مفهومی یا تمرین عملی، با این همه قاعده‌ای که برای این نوع تمرین‌ها وجود دارد، می‌تواند دلهره‌آور باشد. به همین دلیل، بررسی اولیه توسط نگهدارنده اغلب دو تا سه ساعت طول می‌کشد و به ده‌ها نظر منجر می‌شود. برای تمرین‌های مفهومی، فایل‌هایی هم با اهداف/محتوای مشابه وجود دارد (مثلاً معرفی تمرین و معرفی مفهوم) که پیش از پراکنده شدن به موضوعات دیگر، تمرکز بر بی‌نقص کردن یکی از آن‌ها ضروری است.

برای روان‌تر شدن این روند، توصیه‌های زیر را آماده کرده‌ایم.

توصیه: بررسی اولیه را به یک نگهدارنده‌ی ارشد بسپارید

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

  • کار بررسی تکراری انجام نمی‌شود
  • مشارکت‌کننده و نگهدارنده به‌صورت جفتی روی Pull Request کار می‌کنند و امیدواریم این حس را به مشارکت‌کننده بدهد که تنها نیست
  • نظر متناقضی از سوی نگهدارندگان دیگر وجود نخواهد داشت

توصیه: با وضعیت wip ادغام کنید

وقتی مشارکت‌کننده و نگهدارنده هر دو از تمرین راضی شدند، تمرین باید با status تنظیم‌شده روی wip (در حال انجام) ادغام شود. تمرین‌هایی که این وضعیت را دارند برای دانش‌آموزان در دسترس نخواهند بود، اما مربیان برتر ما می‌توانند آن‌ها را ببینند (زمانی که در آینده این امکان را پیاده‌سازی کنیم). این کاربران با اعتبار بالا می‌توانند تمرین را آزمایش کنند و ایشو یا Pull Request بسازند تا تمرین را اصلاح یا بهتر کنند.

مزایای اصلی این روش عبارت‌اند از:

  • بار بی‌نقص بودن همه‌چیز را از دوش جفتِ اصلی مشارکت‌کننده و نگهدارنده برمی‌دارد
  • به چرخه‌های بزرگ Pull Request با صداهای متعدد منجر نمی‌شود (که مدیریت‌شان واقعاً سخت است)

بررسی Pull Requestهای تمرین عملی

توصیه: در نظر بگیرید که آیا این تغییر واقعاً به problems-specifications مربوط است

بخشی از محتوای یک تمرین عملی (مثلاً معرفی آن) از فراداده‌ی (مشترک) آن می‌آید که در مخزن problems-specifications تعریف شده است. وقتی Pull Requestی را بررسی می‌کنید که چنین محتوایی را تغییر می‌دهد، در نظر بگیرید که آیا این تغییر می‌تواند برای مسیرهای دیگر هم مفید باشد. اگر چنین است، به مشارکت‌کننده پیشنهاد دهید که برای فایل مربوطه در مخزن problems-specifications یک Pull Request باز کند.

توصیه‌های کلی بررسی

توصیه: یک بررسی‌کننده‌ی اصلی برای هر Pull Request

هر Pull Request باید یک بررسی‌کننده‌ی اصلی داشته باشد (هر نگهدارنده‌ای که آن را بر عهده می‌گیرد). سایر نگهدارندگان و/یا اعضای جامعه باید در نقش ثانویه عمل کنند.

فردی که در نقش ثانویه است به دو شکل اصلی می‌تواند در یک بررسی مشارکت کند:

  • غلط‌گیری املا/دستور زبان، اما فقط پس از آنکه بررسی‌کننده‌ی اصلی دور اول بررسی را انجام داد. اگر مشارکت‌کننده یک بررسی املا/دستور زبان بگیرد، آن را اصلاح کند و بعد نگهدارنده‌ای سر برسد و از او بخواهد تغییرات بنیادی‌تری بدهد، می‌تواند ناامیدکننده باشد. به بیان دیگر: غلط‌گیری کاری است که پس از مرتب شدن تغییرات بنیادی انجام می‌دهید (یا احتمالاً در یک Pull Request پیگیری).
  • اشاره کردن به مواردی به شکلی غیراقدامی برای بررسی‌کننده. اگر درباره‌ی مواردی نظر می‌دهید که بررسی‌کننده‌ی اصلی باید به آن‌ها فکر کند یا ممکن است از قلم انداخته باشد، لطفاً نظر خود را به شکل بیان یک عقیده یا در قالب پرسش بنویسید. این کار برای مشارکت‌کننده روشن می‌کند که از او نمی‌خواهید تغییری بدهد و سردرگمی او را کمتر می‌کند. همچنین احتمال اینکه بررسی‌کننده‌ی اصلی احساس کند «تضعیف» شده است را کاهش می‌دهد.

توصیه: درباره‌ی موارد نامرتبط نظر ندهید

وقتی یک Pull Request را بررسی می‌کنید، فقط درباره‌ی مواردی نظر دهید که مستقیماً به آن Pull Request مربوط‌اند. اگر مورد دیگری هست، لطفاً یک ایشو باز کنید یا یک Pull Request جداگانه (پیگیری) بسازید.

توصیه: به مستندات پیوند بدهید

هر جا ممکن است، همیشه بکوشید به مستنداتی پیوند بدهید که توضیح می‌دهد چرا درباره‌ی موضوعی نظر می‌دهید. این کار به‌شدت به کاهش احتمال جدل‌آمیز شدن بحث کمک می‌کند.

توصیه: از تیم‌های دیگر کمک بخواهید

اگر می‌خواهید برای بررسی یک Pull Request کمک بگیرید، دو تیم مشخص هستند که می‌توانید آن‌ها را صدا بزنید:

  • @exercism/reviewers: برای هر بررسی عمومی
  • @exercism/github-actions: برای هر پرسشی درباره‌ی GitHub actions