ایجاد تغییرات قطعی در بازل اجتناب ناپذیر است. ما باید طرح های خود را تغییر دهیم و مواردی را که کاملاً کار نمی کنند اصلاح کنیم. با این حال، ما باید اطمینان حاصل کنیم که جامعه و اکوسیستم بازل می توانند از این راه پیروی کنند. برای این منظور، پروژه Bazel یک سیاست سازگاری با عقب را اتخاذ کرده است. این سند روندی را برای مشارکت کنندگان Bazel برای ایجاد یک تغییر اساسی در Bazel برای پایبندی به این خط مشی شرح می دهد.
از خط مشی سند طراحی پیروی کنید.
مشکل GitHub
یک مشکل GitHub را در مخزن Bazel ثبت کنید. نمونه را ببینید.
توصیه می کنیم که:
عنوان با نام پرچم شروع می شود (نام پرچم با
incompatible_شروع می شود).شما برچسب
incompatible-changeرا اضافه می کنید.توضیحات شامل توضیحات تغییر و پیوندی به اسناد طراحی مربوطه است.
توضیحات حاوی دستور العمل مهاجرت است، تا به کاربران توضیح دهد که چگونه باید کد خود را به روز کنند. در حالت ایده‌آل، زمانی که تغییر مکانیکی است، پیوندی به ابزار مهاجرت اضافه کنید.
توضیحات شامل نمونه ای از پیام خطایی است که کاربران در صورت عدم مهاجرت دریافت می کنند. این موضوع باعث می شود که مشکل GitHub از موتورهای جستجو بیشتر قابل کشف باشد. مطمئن شوید که پیام خطا مفید و قابل اجرا است. در صورت امکان، پیام خطا باید شامل نام پرچم ناسازگار باشد.
برای ابزار مهاجرت، مشارکت در Buildifier را در نظر بگیرید. این می تواند اصلاحات خودکار را برای فایل های BUILD ، WORKSPACE و .bzl . اعمال کند. همچنین ممکن است هشدارهایی را گزارش کند.
پیاده سازی
یک پرچم جدید در Bazel ایجاد کنید. مقدار پیش فرض باید نادرست باشد. متن راهنما باید حاوی آدرس اینترنتی مشکل GitHub باشد. از آنجایی که نام پرچم با incompatible_ شروع می شود، به تگ های ابرداده نیاز دارد:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
در توضیحات commit، خلاصه‌ای از پرچم را اضافه کنید. RELNOTES: را نیز به شکل زیر اضافه کنید: RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
commit همچنین باید مستندات مربوطه را به روز کند، به طوری که هیچ پنجره ای از commit وجود نداشته باشد که کد در آن با اسناد مغایرت داشته باشد. از آنجایی که اسناد ما نسخه‌بندی شده است، تغییرات در اسناد به‌طور ناخواسته و پیش از موعد منتشر نمی‌شوند.
برچسب ها
هنگامی که commit ادغام شد و تغییر ناسازگار آماده پذیرش شد، برچسب migration-ready را به مشکل GitHub اضافه کنید.
اگر مشکلی در پرچم پیدا شد و انتظار نمی رود کاربران هنوز migration-ready کنند: پرچم ها را حذف کنید.
اگر قصد دارید پرچم را در نسخه اصلی بعدی برگردانید، برچسب «breaking-change-X.0» را به موضوع اضافه کنید.
به روز رسانی مخازن
Bazel CI لیستی از پروژه های مهم را در Bazel@HEAD + Downstream آزمایش می کند. اکثر آنها اغلب وابسته به پروژه های دیگر Bazel هستند، بنابراین مهاجرت آنها برای رفع انسداد مهاجرت برای جامعه گسترده تر مهم است.
برای نظارت بر وضعیت مهاجرت آن پروژه ها، می توانید از خط لوله bazelisk-plus-incompatible-flags استفاده کنید، نحوه عملکرد این خط لوله را در اینجا بررسی کنید.
انتقال پروژه ها در خط لوله پایین دست کاملاً بر عهده نویسنده تغییرات ناسازگار نیست. اما می توانید برای تسریع در مهاجرت و تسهیل زندگی هم برای کاربران بازل و هم برای تیم سبز بازل موارد زیر را انجام دهید.
- مشکلات Github را برای اطلاع صاحبان پروژه های پایین دستی که به دلیل تغییر ناسازگار شما شکسته شده اند، فایل کنید.
- برای تعمیر پروژه های پایین دستی PR ارسال کنید.
- برای کمک در مورد مهاجرت با انجمن Bazel تماس بگیرید (به عنوان مثال Bazel Rules Authors SIG ).
به اهتزاز درآوردن پرچم
قبل از برگرداندن مقدار پیش فرض پرچم به true، لطفاً مطمئن شوید که:
مخازن اصلی در اکوسیستم مهاجرت می کنند.
در خط لوله
bazelisk-plus-incompatible-flags، پرچم باید درThe following flags didn't break any passing Bazel team owned/co-owned projects.نگرانی ها و سوالات کاربران برطرف شده است.
هنگامی که پرچم آماده چرخاندن در Bazel است، اما در انتقال داخلی در Google مسدود شده است، لطفاً مقدار پرچم را روی false در فایل blazerc داخلی برای رفع انسداد تلنگر پرچم در نظر بگیرید. با انجام این کار، می توانیم اطمینان حاصل کنیم که کاربران Bazel به صورت پیش فرض به رفتار جدید در اسرع وقت وابسته هستند.
هنگام تغییر پیش‌فرض پرچم به true، لطفاً:
- از
RELNOTES[INC]در توضیحات commit با فرمت زیر استفاده کنید:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for detailsمی توانید اطلاعات اضافی را در بقیه توضیحات commit قرار دهید. - از
Fixes #xyzدر توضیحات استفاده کنید تا مشکل GitHub با ادغام شدن commit بسته شود. - در صورت نیاز اسناد را بررسی و به روز کنید.
- برای پیگیری حذف پرچم، یک شماره جدید
#abcکنید.
برداشتن پرچم
پس از برگرداندن پرچم در HEAD، در نهایت باید از Bazel حذف شود. وقتی قصد حذف پرچم ناسازگار را دارید:
- اگر تغییر ناسازگار عمده ای است، زمان بیشتری را برای مهاجرت به کاربران در نظر بگیرید. در حالت ایده آل، پرچم باید حداقل در یک نسخه اصلی در دسترس باشد.
- برای commit که پرچم را حذف می کند، از
Fixes #abcدر توضیحات استفاده کنید تا مشکل GitHub با ادغام commit بسته شود.