במצב בלתי סביר, נבצע שינויים בבזל. נצטרך לשנות את העיצובים שלנו ולתקן את הדברים שלא עובדים. עם זאת, עלינו לוודא שהסביבה העסקית והסביבה העסקית של Bazel יכולות לפעול בהתאם. לשם כך, בזל יזם מדיניות תאימות לאחור. מסמך זה מתאר את התהליך של תורמים ב-Bazel לבצע שינוי אולטימטיבי ב-Bazel לפעול בהתאם למדיניות זו.
יש לפעול בהתאם למדיניות בנושא מסמכי עיצוב.
בעיה ב-GitHub
מדווחים על בעיה ב-GitHub במאגר של Bazel. ראו דוגמה.
אנו ממליצים לך:
שם הדגל מתחיל בשם הדגל (שם הדגל יתחיל ב-
incompatible_).אתם מוסיפים את התווית
incompatible-change.בתיאור יש תיאור של השינוי וקישור למסמכי עיצוב רלוונטיים.
התיאור מכיל מתכון להעברה, כדי להסביר למשתמשים איך הם צריכים לעדכן את הקוד שלהם. באופן אידיאלי, כשהשינוי הוא מכני, יש לכלול קישור לכלי העברה.
התיאור כולל דוגמה להודעת השגיאה שהמשתמשים יקבלו אם הם לא יועברו. כך יהיה קל יותר לגלות את בעיית GitHub ממנועי חיפוש. יש לוודא שהודעת השגיאה שימושית וניתנת לפעולה. כשהדבר יתאפשר, הודעת השגיאה תכלול את שם הדגל הלא תואם.
עבור כלי ההעברה, מומלץ להוסיף תוכן
לכלי ליצירת אתרים.
ניתן להחיל בו תיקונים אוטומטיים על קבצים מסוג BUILD, WORKSPACE ו-.bzl.
הוא יכול גם לדווח על אזהרות.
יישום
יוצרים סימון חדש ב-Bazel. ערך ברירת המחדל חייב להיות False. טקסט העזרה צריך לכלול את כתובת ה-URL של בעיית GitHub. כאשר שם הדגל מתחיל ב-incompatible_, הוא צריך תגי מטא-נתונים:
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
בתיאור המחויבות, מוסיפים סיכום קצר של הדגל.
כמו כן, צריך להוסיף את RELNOTES: בטופס הבא:
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
המחויבות צריכה גם לעדכן את התיעוד הרלוונטי, כך שלא יהיה חלון זמן של מחויבות שבו הקוד לא תואם למסמכים. מאחר שהתיעוד שלנו כולל גרסאות, השינויים במסמכים לא יפורסמו באופן יזום.
תוויות
לאחר מיזוג ההתחייבות והשינוי הלא תואם מוכן להתאמה, יש להוסיף את התווית
migration-ready
לבעיה ב-GitHub.
אם זוהתה בעיה בדגל והמשתמשים עדיין לא צפויים לעבור:
הסירו את הסימונים migration-ready.
אם בכוונתך להפוך את הדגל במהדורה הראשית הבאה, יש להוסיף לבעיה את התווית 'breaking-change-X.0".
מתבצע עדכון של מאגרים
Bazel CI בודק רשימה של פרויקטים חשובים בכתובת Bazel@HEAD + Downstream. רובן תלויות בפרויקטים אחרים של Bazel, ולכן חשוב להעביר אותן כדי לבטל את החסימה של הקהילה כולה.
כדי לעקוב אחר סטטוס ההעברה של הפרויקטים האלה, ניתן להשתמש בצינור עיבוד הנתונים של bazelisk-plus-incompatible-flags, כאן מוסבר איך עובד צינור עיבוד הנתונים הזה.
העברת פרויקטים בצינור עיבוד הנתונים במורד הנהר אינה באחריותו המלאה של מחבר השינוי הלא תואם. עם זאת, אפשר לבצע את הפעולות הבאות כדי להאיץ את ההעברה ולהקל על משתמשי Bazel וגם על צוות Bazel Green.
- לדווח על בעיות של GitHub כדי ליידע את הבעלים של הפרויקטים ב-downstream שחלו בהם בעקבות השינוי הלא תואם.
- שליחת יחסי ציבור כדי לתקן פרויקטים במורד הזרם.
- צרו קשר עם הקהילה של Bazel כדי לקבל עזרה במיגרציה (למשל, Bazel Rules Authors SIG).
החלקה על הדגל
לפני שממירים את ערך ברירת המחדל של הדגל ל'נכון', חשוב לוודא את הדברים הבאים:
מתבצעת העברה של מאגרי הליבה בסביבה העסקית.
בצינור עיבוד הנתונים של
bazelisk-plus-incompatible-flags, הדגל אמור להופיע מתחת ל-The following flags didn't break any passing Bazel team owned/co-owned projects.החששות של המשתמשים והשאלות שלהם נפתרו.
כאשר הדגל מוכן להיפוך בבזל, אך נחסם בהעברה פנימית ב-Google, כדאי לשקול להגדיר את ערך הסימון כ-false בקובץ blazerc הפנימי כדי לבטל את חסימת ההיפוך. כך, אנחנו יכולים להבטיח שמשתמשי Bazel יהיו תלויים בהתנהגות החדשה כברירת מחדל בהקדם האפשרי.
כשמשנים את ברירת המחדל של הסימון ל'נכון', צריך:
- צריך להשתמש במאפיין
RELNOTES[INC]בתיאור ההתחייבות, בפורמט הבא:RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for detailsאפשר להוסיף מידע נוסף לשאר תיאור ההתחייבות. - השתמשו ב-
Fixes #xyzבתיאור, כדי שהבעיה ב-GitHub תיסגר כשהמיזוג ימוזג. - בודקים את המסמכים ומעדכנים אותם לפי הצורך.
- עליך להגיש בעיה חדשה
#abcכדי לעקוב אחר הסרת הסימון.
הסרת הדגל
לאחר הצבת הדגל ב-HEAD, הוא יוסר בסופו של דבר מ-Bazel. אם בכוונתך להסיר את הדגל הלא תואם:
- אם למשתמשים יש שינוי משמעותי ולא תואם, מומלץ להמתין יותר זמן. באופן אידיאלי, הדגל צריך להיות זמין בגרסה ראשית אחת לפחות.
- בהתחייבות שמסירת את הסימון, משתמשים ב-
Fixes #abcבתיאור כדי שהבעיה ב-GitHub תיסגר לאחר המיזוג.