این سند برای مشارکت کنندگان Bazel هدف قرار گرفته است.
توضیحات تعهد در Bazel شامل یک برچسب RELNOTES: به دنبال یک یادداشت انتشار است. این توسط تیم Bazel برای پیگیری تغییرات در هر نسخه و نوشتن اطلاعیه انتشار استفاده می شود.
بررسی اجمالی
آیا تغییر شما رفع اشکال است؟ در این صورت، نیازی به یادداشت انتشار ندارید. لطفاً یک مرجع به مشکل GitHub اضافه کنید.
اگر تغییر، Bazel را به صورت قابل مشاهده توسط کاربر اضافه، حذف یا تغییر دهد، ذکر آن ممکن است سودمند باشد.
اگر تغییر قابل توجه است، ابتدا خط مشی سند طراحی را دنبال کنید.
رهنمودها
یادداشت‌های انتشار توسط کاربران ما خوانده می‌شود، بنابراین باید کوتاه باشد (در حالت ایده‌آل یک جمله)، از اصطلاحات تخصصی (اصطلاحات درونی Bazel) اجتناب شود، باید بر آنچه تغییر است تمرکز کند.
پیوندی به اسناد مربوطه وارد کنید. تقریباً هر یادداشت انتشار باید حاوی یک پیوند باشد. اگر در توضیحات یک پرچم، یک ویژگی، یک نام فرمان ذکر شده باشد، کاربران احتمالاً مایلند در مورد آن بیشتر بدانند.
از نقل قول ها در اطراف کد، نمادها، پرچم ها یا هر کلمه ای که دارای زیرخط است استفاده کنید.
فقط توضیحات اشکال را کپی و جایگذاری نکنید. آنها اغلب رمزآلود هستند و فقط برای ما معنی دارند و کاربر را در حال خاراندن سر خود رها می کنند. یادداشت‌های انتشار به منظور توضیح آنچه تغییر کرده و چرا به زبانی قابل فهم برای کاربر است.
همیشه از زمان حال و فرمت "بازل اکنون Y را پشتیبانی می کند" یا "X اکنون Z را انجام می دهد" استفاده کنید. ما نمی خواهیم یادداشت های انتشار ما مانند ورودی های اشکال به نظر برسند. همه نوشته‌های یادداشت انتشار باید آموزنده باشند و از سبک و زبان ثابتی استفاده کنند.
اگر چیزی منسوخ شده یا حذف شده است، از «X منسوخ شده است» یا «X حذف شده است» استفاده کنید. نه «حذف شد» یا «حذف شد».
اگر Bazel اکنون کاری متفاوت انجام می دهد، از "X now $newBehavior به جای $oldBehavior" در زمان حال استفاده کنید. این به کاربر اجازه می‌دهد تا بداند هنگام استفاده از نسخه جدید چه چیزی باید انتظار داشته باشد.
اگر Bazel اکنون چیزی را پشتیبانی می‌کند یا دیگر پشتیبانی نمی‌کند، از «Bazel now supports/nother supports X» استفاده کنید.
توضیح دهید که چرا چیزی حذف شده / منسوخ شده / تغییر یافته است. یک جمله کافی است اما ما می خواهیم که کاربر بتواند تاثیر روی ساخت های خود را ارزیابی کند.
هیچ قولی در مورد عملکرد آینده ندهید. از "این پرچم حذف خواهد شد" یا "این تغییر خواهد کرد" اجتناب کنید. عدم قطعیت را معرفی می کند. اولین چیزی که کاربر تعجب می کند این است که "چه زمانی؟" و ما نمی خواهیم آنها نگران خراب شدن بیلدهای فعلی خود در زمان نامعلومی باشند.
روند
به عنوان بخشی از فرآیند انتشار ، ما تگ های RELNOTES هر commit را جمع آوری می کنیم. ما همه چیز را در Google Doc کپی می کنیم، جایی که یادداشت ها را مرور، ویرایش و سازماندهی می کنیم.
مدیر انتشار یک ایمیل به لیست پستی bazel-dev ارسال می کند. از مشارکت کنندگان Bazel دعوت می شود تا در سند مشارکت کنند و مطمئن شوند که تغییرات آنها به درستی در اطلاعیه منعکس شده است.
بعداً این اطلاعیه با استفاده از مخزن بازل بلاگ به وبلاگ بازل ارسال خواهد شد.