اگر قصد اضافه کردن، تغییر یا حذف یک ویژگی رو به روی کاربر، یا ایجاد یک تغییر معماری قابل توجه در Bazel را دارید، باید قبل از ارسال تغییر، یک سند طراحی بنویسید و آن را بررسی کنید.
در اینجا چند نمونه از تغییرات قابل توجه آورده شده است:
- افزودن یا حذف قوانین ساخت بومی
- شکستن تغییرات در قوانین بومی
- تغییرات در معنایی قوانین ساخت بومی که بر رفتار بیش از یک قانون تأثیر می گذارد
- تغییرات در API تعریف قانون Bazel
- تغییرات در API هایی که Bazel برای اتصال به سیستم های دیگر استفاده می کند
- تغییرات در زبان Starlark، معناشناسی یا APIها
- تغییراتی که می‌تواند تأثیری فراگیر بر عملکرد Bazel یا استفاده از حافظه داشته باشد (برای بهتر یا بد)
- تغییرات در APIهای داخلی پرکاربرد
- تغییرات در پرچم ها و رابط خط فرمان.
دلایل بررسی طراحی
هنگامی که یک سند طراحی می نویسید، می توانید با سایر توسعه دهندگان Bazel هماهنگ شده و از تیم اصلی Bazel راهنمایی بخواهید. برای مثال، هنگامی که یک پروپوزال هر تابع یا شی موجود در فایل‌های BUILD، WORKSPACE یا bzl را اضافه، حذف یا تغییر می‌دهد، تیم Starlark را به عنوان بازبین اضافه کنید. اسناد طراحی قبل از ارسال بررسی می شوند زیرا:
- بازل یک سیستم بسیار پیچیده است. تغییرات محلی به ظاهر بی ضرر می تواند پیامدهای جهانی قابل توجهی داشته باشد.
- این تیم درخواست های زیادی از کاربران دریافت می کند. چنین درخواست هایی باید نه تنها از نظر امکان سنجی فنی، بلکه از نظر اهمیت با توجه به سایر درخواست های ویژگی مورد ارزیابی قرار گیرند.
- ویژگی های Bazel اغلب توسط افراد خارج از تیم اصلی اجرا می شود. چنین مشارکت کنندگانی دارای سطوح بسیار متفاوتی از تخصص Bazel هستند.
- تیم بازل خود دارای سطوح مختلفی از تخصص است. هیچ یک از اعضای تیم به تنهایی درک کاملی از هر گوشه از Bazel ندارد.
- تغییرات در Bazel باید به دلیل سازگاری با عقب و جلوگیری از شکستن تغییرات باشد.
خط مشی بررسی طراحی Bazel به حداکثر رساندن این احتمال کمک می کند:
- همه درخواست‌های ویژگی یک سطح پایه بررسی را دریافت می‌کنند.
- افراد مناسب قبل از سرمایه‌گذاری روی طرح‌ها که ممکن است کارساز نباشد، بررسی می‌کنند.
برای کمک به شما برای شروع، نگاهی به اسناد طراحی در مخزن پیشنهادات Bazel بیندازید. طراحی ها در حال انجام هستند، بنابراین جزئیات پیاده سازی می تواند در طول زمان و با بازخورد تغییر کند. اسناد طراحی منتشر شده، طراحی اولیه را نشان می‌دهد، و نه تغییرات مداوم در حین اجرای طرح‌ها. برای توضیحات عملکرد فعلی Bazel، همیشه به مستندات مراجعه کنید.
گردش کار مشارکت کننده
به‌عنوان مشارکت‌کننده، می‌توانید یک سند طراحی بنویسید، درخواست‌های کششی ارسال کنید و از بازبینی‌کنندگان برای پیشنهاد خود درخواست کنید.
سند طراحی را بنویسید
تمام اسناد طراحی باید دارای یک سربرگ باشد که شامل موارد زیر باشد:
- نویسنده
- تاریخ آخرین تغییر عمده
- فهرستی از داوران، شامل یک (و تنها یک) بازبین اصلی
- وضعیت فعلی ( پیش نویس ، در حال بررسی ، تایید ، رد ، در حال اجرا ، اجرا )
- پیوند به موضوع بحث ( پس از اعلام اضافه خواهد شد )
سند را می‌توان به‌عنوان Google Doc خوانا در جهان یا با استفاده از Markdown نوشت. برای مقایسه Markdown / Google Docs در زیر بخوانید.
پیشنهادهایی که تأثیر قابل مشاهده برای کاربر دارند باید دارای بخشی باشند که تأثیر آن بر سازگاری با عقب را مستند کند (و در صورت نیاز یک طرح عرضه).
یک درخواست کشش ایجاد کنید
با ایجاد یک درخواست کشش (PR) برای افزودن سند به نمایه طراحی، سند طراحی خود را به اشتراک بگذارید. فایل علامت گذاری یا پیوند سند خود را به روابط عمومی خود اضافه کنید.
در صورت امکان، یک بازبین اصلی انتخاب کنید . و سی سی بازبینان دیگر. اگر بازبین اصلی را انتخاب نکنید، نگهدارنده Bazel یکی را به روابط عمومی شما اختصاص می دهد.
پس از ایجاد روابط عمومی خود، بازبینان می توانند نظرات اولیه را در طول بررسی کد ارائه دهند. برای مثال، بازبین اصلی می‌تواند بازبین‌های دیگری را پیشنهاد کند، یا به اطلاعات گمشده اشاره کند. بازبین اصلی زمانی PR را تأیید می کند که معتقد باشد روند بررسی می تواند شروع شود. این بدان معنا نیست که پیشنهاد کامل است یا تایید خواهد شد. این بدان معناست که پروپوزال حاوی اطلاعات کافی برای شروع بحث است.
پیشنهاد جدید را اعلام کنید
زمانی که PR ارسال شد، یک اطلاعیه به bazel-dev ارسال کنید.
می توانید گروه های دیگر را کپی کنید (به عنوان مثال، bazel-discuss ، برای دریافت بازخورد از کاربران نهایی Bazel).
با بازبینان تکرار کنید
هر علاقه مند می تواند در مورد پیشنهاد شما نظر دهد. سعی کنید به سوالات پاسخ دهید، پیشنهاد را روشن کنید و نگرانی ها را برطرف کنید.
بحث باید در تاپیک اطلاعیه انجام شود. اگر پیشنهاد در Google Doc باشد، می‌توان از نظرات به جای آن استفاده کرد (توجه داشته باشید که نظرات ناشناس مجاز هستند).
وضعیت را به روز کنید
پس از اتمام تکرار، یک PR جدید برای به‌روزرسانی وضعیت پیشنهاد ایجاد کنید. PR را برای همان بازبین اصلی ارسال کنید و سایر بازبینان را cc کنید.
برای پذیرش رسمی پیشنهاد، بازبین اصلی پس از اطمینان از موافقت سایر بازبینان با تصمیم، PR را تأیید می کند.
بین اولین اطلاعیه تا تایید یک پیشنهاد حداقل یک هفته فاصله باشد. این تضمین می کند که کاربران زمان کافی برای خواندن سند و به اشتراک گذاشتن نگرانی های خود دارند.
اجرا می تواند قبل از پذیرفته شدن پروپوزال آغاز شود، به عنوان مثال به عنوان یک اثبات مفهوم یا یک آزمایش. با این حال، نمی توانید قبل از تکمیل بررسی، تغییر را ارسال کنید.
انتخاب یک بازبین اصلی
یک بازبین اصلی باید یک متخصص حوزه باشد که:
- آشنا به زیرسیستم های مربوطه
- هدفمند و قادر به ارائه بازخورد سازنده است
- برای کل دوره بررسی برای هدایت فرآیند در دسترس است
بررسی مخاطبین برای برچسب های مختلف تیم را در نظر بگیرید.
Markdown در مقابل Google Docs
تصمیم بگیرید که چه چیزی برای شما بهتر است، زیرا هر دو مورد قبول هستند.
مزایای استفاده از Google Docs:
- برای طوفان فکری موثر است، زیرا شروع با آن آسان است.
- ویرایش مشارکتی
- تکرار سریع
- راه آسان برای پیشنهاد ویرایش
مزایای استفاده از فایل های Markdown:
- URL ها را برای پیوند پاک کنید.
- سابقه صریح تجدید نظرها.
- فراموش نکنید که قبل از انتشار یک پیوند، حقوق دسترسی را تنظیم کنید.
- به راحتی با موتورهای جستجو قابل جستجو است.
- ضد آینده: متن ساده در اختیار هیچ ابزار خاصی نیست و نیازی به اتصال به اینترنت ندارد.
- حتی اگر نویسنده دیگر در اطراف نباشد، می توان آنها را به روز کرد.
- آنها را می توان به طور خودکار پردازش کرد (به روز رسانی / شناسایی پیوندهای مرده، واکشی لیست نویسندگان، و غیره).
می توانید انتخاب کنید که ابتدا در Google Doc تکرار شود و سپس آن را برای آیندگان به Markdown تبدیل کنید.
با استفاده از Google Docs
برای سازگاری، از الگوی مستند طراحی Bazel استفاده کنید . این شامل هدر لازم است و هماهنگی بصری با سایر اسناد مرتبط با Bazel ایجاد می کند. برای انجام این کار، روی File > Make a copy یا روی این پیوند کلیک کنید تا یک کپی از الگوی طراحی سند ایجاد کنید .
برای اینکه سند خود را برای دنیا خوانا کنید، روی Share > Advanced > Change… کلیک کنید و "On - Anyone with the link" را انتخاب کنید. اگر اجازه نظر دادن در مورد سند را بدهید، هر کسی می‌تواند به صورت ناشناس نظر دهد، حتی بدون حساب Google.
با استفاده از Markdown
اسناد در GitHub ذخیره می شوند و از طعم GitHub Markdown ( مشخصات ) استفاده می کنند.
برای به روز رسانی یک سند موجود، یک روابط عمومی ایجاد کنید. تغییرات مهم باید توسط بازبینان اسناد بررسی شود. تغییرات بی اهمیت (مانند غلط املایی، قالب بندی) می تواند توسط هر کسی تایید شود.
گردش کار بازبین
یک بازبین نظرات، بررسی و تایید اسناد طراحی را می دهد.
مسئولیت های کلی داور
شما مسئول بررسی اسناد طراحی، درخواست اطلاعات اضافی در صورت نیاز، و تایید طرحی هستید که فرآیند بررسی را پشت سر بگذارد.
وقتی پیشنهاد جدیدی دریافت می کنید
- نگاهی گذرا به سند بیندازید.
- اگر اطلاعات حیاتی از دست رفته است، یا اگر طرح با اهداف پروژه مطابقت ندارد، نظر دهید.
- بازبین های بیشتری را پیشنهاد دهید.
- زمانی که روابط عمومی برای بررسی آماده شد، تأیید کنید.
در طول فرآیند بررسی
- در مورد موضوعاتی که مشکل ساز هستند یا نیاز به توضیح دارند، با نویسنده طرح گفتگو کنید.
- در صورت اقتضا، نظرات غیر داورانی را که باید از طرح آگاه باشند دعوت کنید.
- تصمیم بگیرید که کدام نظرات باید توسط نویسنده به عنوان پیش نیاز تأیید مورد توجه قرار گیرد.
- هنگامی که از وضعیت فعلی پیشنهاد راضی هستید، "LGTM" ( برای من خوب به نظر می رسد ) در موضوع بحث بنویسید.
این روند را برای همه درخواست‌های بررسی طراحی دنبال کنید. طرح هایی را که بر بازل تأثیر می گذارند در صورتی که در شاخص طراحی نیستند تأیید نکنید.
مسئولیت های بازبین اصلی
شما مسئول تصمیم گیری برای اجرای یک طرح معلق هستید. اگر قادر به انجام این کار نیستید، باید یک نماینده مناسب را شناسایی کنید (تخصیص مجدد روابط عمومی به نماینده)، یا اشکال را به یک مدیر Bazel برای بررسی بیشتر اختصاص دهید.
در طول فرآیند بررسی
- اطمینان حاصل کنید که فرآیند اظهار نظر و تکرار طرح به طور سازنده پیش می رود.
- قبل از تأیید، اطمینان حاصل کنید که نگرانی های دیگر بازبینان برطرف شده است.
پس از تایید توسط همه داوران
- مطمئن شوید که حداقل 1 هفته از زمان اعلام در لیست پستی گذشته است.
- اطمینان حاصل کنید که روابط عمومی وضعیت را به روز می کند.
- PR ارسال شده توسط نویسنده پیشنهاد را تایید کنید.
رد طرح ها
- مطمئن شوید که نویسنده روابط عمومی یک PR ارسال می کند. یا برایشان PR ارسال کنید.
- PR وضعیت سند را به روز می کند.
- نظری به سند اضافه کنید و توضیح دهید که چرا طرح را نمی‌توان در وضعیت فعلی تأیید کرد، و در صورت وجود، مراحل بعدی را تشریح کرد (مانند «بازبینی مفروضات نامعتبر و ارسال مجدد»).