هرکسی میتواند یک Pull Request مربوط به مستندات را بازبینی (review) کند. برای دیدن Pull Requestهای باز، به بخش
pull requests در مخزن وبسایت کوبرنتیز بروید.
بازبینی Pull Requestهای مستندات راه بسیار خوبی برای معرفی خود به جامعه کوبرنتیز است؛
به شما کمک میکند با پایگاه کد آشنا شوید و اعتماد سایر مشارکتکنندگان را جلب کنید.
علاوه بر تغییرات، بر جنبههای مثبت PRها نیز نظر بگذارید.
همدل باشید و در نظر داشته باشید بازبینی شما چگونه دریافت میشود.
نیت خوب را فرض کنید و پرسشهای روشنکننده بپرسید.
مشارکتکنندگان باتجربه، با مشارکتکنندگان تازهای که کارشان نیاز به تغییرات گسترده دارد جفت شوید.
فرایند بازبینی
بهطور کلی، Pull Requestها را از نظر محتوا و سبک به زبان انگلیسی بازبینی کنید.
شکل ۱ گامهای فرایند بازبینی را نشان میدهد؛ جزئیات هر گام در ادامه آمده است.
flowchart LR
subgraph fourth[Start review]
direction TB
S[ ] -.-
M[add comments] --> N[review changes]
N --> O[new contributors should choose Comment]
end
subgraph third[Select PR]
direction TB
T[ ] -.-
J[read description and comments]--> K[preview changes in Netlify preview build]
end
A[Review open PR list]--> B[Filter open PRs by label]
B --> third --> fourth
classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,J,K,M,N,O grey
class S,T spacewhite
class third,fourth white
Pull Requestهای باز را با استفاده از یک یا همه برچسبهای زیر فیلتر کنید:
cncf-cla: yes (پیشنهاد میشود): PRهایی که نویسنده آنها CLA را امضا نکرده است نمیتوانند ادغام شوند.
برای اطلاعات بیشتر بخش، CLA امضا را ببینید.
language/en (پیشنهاد میشود): فقط PRهای زبان انگلیسی را فیلتر میکند.
size/<size>: PRها را بر اساس اندازه فیلتر میکند. اگر تازهکار هستید، با PRهای کوچکتر شروع کنید.
همچنین مطمئن شوید PR با برچسب work in progress علامتگذاری نشده باشد؛
چنین PRهایی هنوز آماده بازبینی نیستند.
پس از انتخاب یک PR برای بازبینی، تغییرات را با انجام کارهای زیر درک کنید:
توضیحات PR را بخوانید تا تغییرات انجامشده را بفهمید و هر Issue پیوندشده را بررسی کنید.
نظرهای سایر بازبینها را بخوانید.
روی تب Files changed کلیک کنید تا فایل ها و خطوط تغییریافته را ببینید.
پیشنمایش تغییرات را در ساخت پیشنمایش Netlify مشاهده کنید. برای این کار، در تب Conversation به بخش بررسی ساخت Netlify که در پایین صفحه قرار دارد بروید. (این تصویر مربوط به نسخه دسکتاپ GitHub است؛ اگر در تبلت یا تلفن همراه بازبینی میکنید، رابط کاربری GitHub کمی متفاوت است):برای باز کردن پیشنمایش، روی پیوند Details در خط deploy/netlify در فهرست بررسیها کلیک کنید.
به تب Files changed بروید تا بازبینی را آغاز کنید.
روی نماد + کنار خطی که میخواهید نظر بدهید کلیک کنید.
نظر خود را درباره آن خط بنویسید و روی Add single comment (اگر تنها یک نظر دارید) یا
Start a review (اگر چند نظر دارید) کلیک کنید.
پس از پایان، در بالای صفحه روی Review changes کلیک کنید. اینجا میتوانید
خلاصهای از بازبینی خود (و چند نظر مثبت برای مشارکتکننده!) بنویسید. لطفاً همیشه از دکمه "Comment" استفاده کنید.
هنگام پایان بازبینی، از کلیک روی دکمه "Request changes" پرهیز کنید. اگر میخواهید پیش از اعمال تغییرات بیشتر مانع ادغام PR شوید، میتوانید کامنت /hold بگذارید.
دلیل hold را ذکر کنید و در صورت تمایل شرایط برداشتن آن را مشخص کنید.
هنگام پایان بازبینی، از کلیک روی دکمه "Approve" پرهیز کنید.
بیشتر مواقع گذاشتن کامنت /approve توصیه میشود.
چکلیست بازبینی
هنگام بازبینی، از موارد زیر بهعنوان نقطه شروع استفاده کنید.
زبان و دستور زبان
آیا خطاهای آشکاری در زبان یا دستور زبان وجود دارد؟ آیا راه بهتری برای بیان یک جمله هست؟
روی زبان و دستور زبان بخشهایی از صفحه که نویسنده تغییر داده تمرکز کنید.
مگر اینکه نویسنده آشکارا قصد بهروزرسانی کل صفحه را داشته باشد، او الزام ندارد
همه اشکالات صفحه را برطرف کند.
وقتی یک PR صفحهای موجود را بهروزرسانی میکند، روی بخشهای تغییر یافته صفحه بازبینی کنید.
آن محتوا باید از نظر فنی و ویرایشی درست باشد. اگر خطاهایی پیدا کردید که مستقیماً به هدف نویسنده مرتبط نیست،
آن را در یک Issue جداگانه مطرح کنید (البته ابتدا مطمئن شوید Issue مشابهی وجود ندارد).
مراقب Pull Requestهایی باشید که محتوا را جابهجا میکنند. اگر نویسنده صفحهای را
تغییر نام میدهد یا دو صفحه را ادغام میکند، ما (SIG Docs کوبرنتیز) معمولاً از او نمیخواهیم
همه ایرادهای املایی یا دستور زبانی موجود در محتوای جابهجا شده را برطرف کند.
آیا واژههای پیچیده یا کهنهای هست که بتوان آنها را با واژهای سادهتر جایگزین کرد؟
آیا واژه، اصطلاح یا عبارتی هست که بتوان آن را با جایگزینی غیرتبعیضآمیز عوض کرد؟
آیا انتخاب واژه و حروف بزرگ/کوچک کردن آن با راهنمای سبک هماهنگ است؟
آیا جملههای طولانی وجود دارد که میتواند کوتاهتر یا سادهتر شود؟
آیا پاراگرافهای طولانی وجود دارد که شاید بهصورت فهرست یا جدول بهتر باشند؟
محتوا
آیا محتوای مشابهی در جای دیگری از سایت کوبرنتیز وجود دارد؟
آیا محتوا بیش از حد به مستندات خارج از وبسایت، مستندات متعلق به یک فروشنده ی خاص یا مستندات غیرمتنباز پیوند میدهد؟
مستندات
چند بررسی که باید در نظر گرفت:
آیا این PR عنوان، slug/alias یا پیوند لنگری (anchor link) صفحهای را تغییر داده یا حذف کرده است؟ اگر بله، آیا در نتیجه این PR پیوندهای شکستهای ایجاد شده است؟ آیا گزینه دیگری مثل تغییر عنوان صفحه بدون تغییر slug وجود دارد؟
آیا PR صفحهای جدید اضافه میکند؟ اگر بله:
آیا صفحه از نوع محتوای صفحه مناسب و شورتکدهای مرتبط Hugo استفاده میکند؟
آیا صفحه در ناوبری جانبی آن بخش بهدرستی نمایش داده میشود (یا اصلاً نمایش داده میشود)؟
آیا تغییرات در پیشنمایش Netlify نمایش داده میشوند؟ درباره فهرستها، بلاکهای کد، جدولها،
نکتهها و تصاویر دقیق باشید.
وبنوشت (blog)
بازخورد زودهنگام درباره پستهای وبنوشت از طریق Google Doc یا HackMD استقبال میشود.
لطفاً درخواست خود را از کانال Slack #sig-docs-blog زودتر ارسال کنید.
همچنین درباره مقالات evergreen و نحوه تصمیمگیری درباره evergreen بودن مقاله اطلاعات داشته باشید.
مقالات وبنوشت ممکن است شامل نقلقول مستقیم و
گفتار غیرمستقیم باشند.
برای متنی که به فردی نسبت داده شده یا بخشی از گفتوگویی واقعی است، پیشنهاد بازنویسی ندهید—حتی اگر
دستور زبان گوینده اصلی درست نباشد. در این موارد همچنین سعی کنید علامات نگارشی پیشنهادی نویسنده را حفظ کنید مگر اینکه واضحاً اشتباه باشد.
بهعنوان پروژه، فقط زمانی مقالات وبنوشت را با برچسب نگهداری (evergreen: true در front matter) علامت میکنیم
که پروژه Kubernetes متعهد باشد آنها را بهطور نامحدود نگهداری کند.
برخی مقالات قطعاً ارزش این کار را دارند و ما همیشه اطلاعیههای انتشار را evergreen علامت میکنیم.
اگر درباره نحوه بازبینی این مورد مطمئن نیستید، با سایر مشارکتکنندگان مشورت کنید.
راهنمای محتوا بدون قید و شرط بر مقالات وبنوشت
و PRهایی که آنها را اضافه میکنند اعمال میشود. به یاد داشته باشید برخی محدودیتها فقط
به مستندات مربوطاند و برای مقالات وبنوشت صدق نمیکنند.
بررسی کنید که منبع Markdown از نوع مناسب محتوای صفحه
و / یا layout مناسب استفاده میکند.
سایر
مراقب ویرایشهای جزئی (Trivial Edits) باشید؛
اگر تغییری را ویرایش جزئی تشخیص میدهید، این سیاست را یادآور شوید
(اگر واقعاً بهبود است، قبول تغییر اشکالی ندارد).
نویسندگانی را که در حال انجام اصلاحات مربوط به فاصلهگذاری (whitespace) هستند تشویق کنید که این کار را در اولین commit PR خود انجام دهند و سپس تغییرات دیگر را روی آن اضافه کنند. این کار هم ادغام (merge) و هم بازبینیها را سادهتر میکند. بهویژه مراقب تغییرات جزئی باشید که همراه با مقدار زیادی اصلاح فاصلهگذاری در یک commit واحد انجام شدهاند (و اگر چنین موردی دیدید، نویسنده را تشویق کنید تا آن را اصلاح کند).
بهعنوان بازبین، اگر مسائل کوچکی در PR یافتید که برای معنا حیاتی نیستند، مثل غلطهای املایی
یا فاصله نادرست، نظر خود را با پیشوند nit: بنویسید.
این به نویسنده نشان میدهد این بخش از بازخورد شما غیر بحرانی است.
اگر در حال بررسی تأیید یک Pull Request هستید و تمام بازخوردهای باقیمانده با nit
علامتگذاری شدهاند، میتوانید PR را ادغام کنید. در این حالت، توصیه میشود برای
موارد nit باقیمانده یک issue جدید باز کنید. همچنین در نظر بگیرید که آیا میتوانید
آن issue جدید را بهعنوان Good First Issue علامتگذاری کنید یا خیر؛
اگر امکانپذیر باشد، این ها منابع خوبی (برای مشارکتکنندگان تازهوارد) خواهند بود.
