מסמכי עיצוב

אם אתם מתכננים להוסיף, לשנות או להסיר תכונה המוצגת למשתמש, או ליצורשינוי ארכיטקטוני משמעותי לבזל, אתחייב כתבו מסמך עיצוב ובדקו אותו לפני שתוכלו לשלוח את השינוי.

הנה כמה דוגמאות לשינויים משמעותיים:

• הוספה או מחיקה של כללי build מותאמים
• מעבר אל שינויים בכללים מותאמים
• שינויים בסמנטיקה של כלל build מקורי שמשפיעים על ההתנהגות של כלל אחד בלבד
• שינויים ב-Bazel API להגדרת הכללים
• שינויים בממשקי ה-API שבהם Bazel משתמשת כדי להתחבר למערכות אחרות
• שינויים בשפה, בסמנטיקה או בממשקי ה-API של Starlark
• שינויים שעשויים להשפיע באופן משמעותי על הביצועים של Bazel או על השימוש בזיכרון (טוב או פחות)
• שינויים בממשקי API פנימיים נפוצים
• שינויים בסימונים ובממשק שורת הפקודה.

סיבות לבדיקות עיצוב

בעת כתיבת מסמך עיצוב, ניתן לתאם עם מפתחים אחרים ב-Bazel ולבקש הדרכה מצוות הליבה של Bazel. לדוגמה, כאשר הצעה מוסיפה, מסירה או משנה כל פונקציה או אובייקט הזמינים בקובצי BUILD , WORKSPACE או bzl, הוסף את צוות Starlark כבודקים. מסמכי עיצוב נבדקים לפני שליחה:

• בזל היא מערכת מורכבת מאוד; שינויים מקומיים תמימים לכאורה עשויים להשפיע באופן גלובלי משמעותי.
• הצוות מקבל ממשתמשים רבים בקשות להוספת תכונות; יש להעריך בקשות כאלה לא רק כדי לבדוק אם ניתן לעשות זאת באופן טכני, אלא אם יש חשיבות לבקשות אחרות.
• אנשים משתמשים מחוץ לליבת התכונות של בזל. לתורמים כאלה יש רמות שונות של מומחיות בבזל.
• לצוות בזל עצמו יש רמות שונות של מומחיות; אין עוד חברי צוות שיש להם הבנה מלאה בכל פינות של בזל.
• שינויים ב-Bazel חייבים להביא בחשבון תאימות לאחור, ולא למנוע תקלות בשינויים.

המדיניות של Bazel לבדיקת עיצוב עוזרת למקסם את הסיכוי:

• כל הבקשות לתכונות מקבלות רמה בסיסית של בחינה קפדנית.
• האנשים הנכונים ישקלו על עיצובים לפני שנשקיע בהטמעה שעשויה לא לעבוד.

כדי לעזור לך להתחיל, מומלץ לעיין במסמכי העיצוב במאגר ההצעות לעמודות. עיצובים פועלים כעת, כך שפרטי היישום עשויים להשתנות עם הזמן ועם משוב. מסמכי העיצוב שפורסמו משקפים את העיצוב הראשוני, ולא את השינויים המתמשכים עם הטמעת העיצובים. עברו תמיד לתיעוד של התיאורים של הפונקציונליות הנוכחית של בזל.

תהליך עבודה של Contributor

כתורם, תוכל לכתוב מסמך עיצוב, לשלוח בקשות משיכה ולבקש מסוקרים להצעה שלך.

כתיבת מסמך העיצוב

לכל מסמכי העיצוב צריכה להיות כותרת שכוללת:

• מחבר
• תאריך השינוי הגדול האחרון
• רשימת הבודקים, כולל כותב ביקורת אחד (ואחד בלבד)
• סטטוס נוכחי (טיוטה, בבדיקה, אושר, נדחה, יושם, יושמה)
• קישור לשרשור דיון (להוספה לאחר ההודעה)

אפשר לכתוב את המסמך כמסמך של Google Docs הקריא בעולם או באמצעות Markup. בהמשך מופיע מידע לגבי השוואה בין תגי עיצוב / השוואת מסמכים ב-Google Docs.

הצעות עם השפעה גלויה למשתמש חייבות לכלול קטע המתעד את ההשפעה על התאימות לאחור (ותוכנית השקה במידת הצורך).

יצירת בקשה למשיכה

כדי לשתף את מסמך העיצוב, אפשר ליצור בקשת משיכה (PR) כדי להוסיף את המסמך לאינדקס העיצוב. הוסיפו את קובץ הסימון או קישור למסמך אל יחסי הציבור.

כשניתן, יש לבחור סוקר לידים. ולהוסיף בודקים אחרים. אם לא תבחרו בודק לידים, מנחה של Bazel יקצה אחד ליחסי הציבור שלכם.

לאחר יצירת יחסי הציבור, כותבי הביקורות יכולים לערוך הערות ראשוניות במהלך בדיקת הקוד. לדוגמה, סוקר הלידים יכול להציע בודקים נוספים, או לציין מידע חסר. כותב הביקורת הראשית מאשר את יחסי הציבור כאשר הוא סבור שתהליך הבדיקה יכול להתחיל. זה לא אומר שההצעה מושלמת או תאושר; המשמעות היא שההצעה כוללת מספיק מידע כדי להתחיל את הדיון.

הכרזה על ההצעה החדשה

ניתן לשלוח הודעה אל bazel-dev עם שליחת ה-PR.

ניתן להעתיק קבוצות אחרות (לדוגמה, דיון בזל, כדי לקבל משוב ממשתמשי קצה של Bazel).

יצירת חזרה עם בודקים

כל מי שרוצה יכול להגיב על ההצעה שלך. נסו לענות על שאלות, להבהיר את ההצעה ולטפל בבעיות.

יש לנהל דיון בשרשור ההודעות. אם ההצעה היא במסמך של Google Docs, ייתכן שייעשה שימוש בתגובות במקום זאת (לתשומת לבך, תגובות אנונימיות מותרות).

עדכון הסטטוס

צור יחסי ציבור חדשים כדי לעדכן את סטטוס ההצעה, לאחר שהחזרה הסתיימה. שולחים את יחסי הציבור לאותו בודק לידים ועותק של הבודקים האחרים.

כדי לקבל את ההצעה באופן רשמי, כותב הביקורת בודק את יחסי הציבור לאחר שווידא שהבודקים האחרים מסכימים עם ההחלטה.

חייב להיות שבוע אחד לפחות בין ההודעה הראשונה לבין האישור של הצעה. כך מובטח שלמשתמשים היה מספיק זמן לקרוא את המסמך ולשתף את חששותיהם.

היישום יכול להתחיל לפני קבלת ההצעה, לדוגמה כהוכחה או כניסוי. עם זאת, לא תוכלו להגיש את השינוי לפני שהבדיקה תושלם.

בחירת בודק לידים

בודק לידים צריך להיות מומחה דומיין:

• בעל ידע על מערכות המשנה הרלוונטיות
• אובייקטיבית ומסוגלת לספק משוב בונה
• זמין לכל תקופת הבדיקה כדי להוביל את התהליך

כדאי לבדוק את אנשי הקשר ולבדוק אם יש תוויות צוות שונות.

מרקד לעומת Google Docs

החלט מה מתאים לך יותר, שכן שני הסוגים מקובלים.

יתרונות השימוש ב-Google Docs:

• יעיל לסיעור מוחות, כי קל להתחיל בעבודה.
• עריכה משותפת.
• חזרה מהירה.
• דרך קלה לשלוח הצעות עריכה.

יתרונות השימוש בקובצי סימון:

• כתובות URL נקיות לקישור.
• תיעוד מפורש של גרסאות קודמות.
• לא לשכוח להגדיר זכויות גישה לפני פרסום קישור.
• מנועי חיפוש מאפשרים חיפוש קל.
• עמידות עתידית: טקסט פשוט לא נחשף לכלי ספציפי ואינו דורש חיבור לאינטרנט.
• אפשר לעדכן אותן גם אם המחבר לא נמצא יותר בסביבה.
• ניתן לעבד אותם באופן אוטומטי (לעדכן/לזהות קישורים שאינם פעילים, לאחזר רשימת מחברים וכו').

תוכלו לבחור קודם כול לחזור על מסמך ב-Google Docs, ואז להמיר אותו לסימון כ'ל חינם' עבור הדורות הבאים.

שימוש ב-Google Docs

כדי לשמור על עקביות, יש להשתמש בתבנית למסמך בפורמט Bazel. היא כוללת את הכותרת הנדרשת ויוצרת עקביות ויזואלית עם מסמכים אחרים הקשורים לבזל. לשם כך, יש ללחוץ על קובץ > יצירת עותק או ללחוץ על קישור זה כדי ליצור עותק של מסמך עיצוב העיצוב.

כדי להגדיר את המסמך כקריא לכולם, לוחצים על שיתוף > מתקדם > שינוי... ובוחרים באפשרות "מופעל -" כל מי שיש לו את הקישור". אם תאפשרו תגובות במסמך, כל אחד יוכל להגיב באופן אנונימי, גם בלי חשבון Google.

שימוש ב-Markup

המסמכים מאוחסנים ב-GitHub ומשתמשים בטעם GitHub של Markdown (מפרט).

צור PR או עדכן מסמך קיים. יש לבדוק באופן משמעותי שינויים משמעותיים על ידי בודקי המסמכים. שינויים טריוויאליים (כמו שגיאות הקלדה, עיצוב) יאושרו על ידי כולם.

תהליך עבודה של כותב הביקורת

כותב הביקורת מגיב, בודק ומאשר מסמכי עיצוב.

האחריות הכללית של בודקים

את/ה אחראי/ת לבדוק מסמכי עיצוב, לבקש מידע נוסף במידת הצורך, ולאשר עיצוב שעובר את תהליך הבדיקה.

כשתקבל הצעה חדשה

1. סקירה מהירה של המסמך.
2. הגיבו אם חסר מידע קריטי, או אם העיצוב לא מתאים ליעדי הפרויקט.
3. הצעת בודקים נוספים.
4. יש לאשר את יחסי הציבור כשהם מוכנים לבדיקה.

בתהליך הבדיקה

1. קיימו דו-שיח עם מחבר העיצוב על בעיות בעייתיות או מצריכות הבהרה.
2. אם רלוונטי, כדאי להזמין תגובות ממשתמשים שלא כתבו ביקורת, שעליהם להיות מודעים לעיצוב.
3. החלט אילו תגובות יש להתייחס למחבר כתנאי מוקדם לאישור.
4. כתוב "LGTM" (נראה טוב ) בשרשור בדיונים כשאתם מרוצים מהמצב הנוכחי של ההצעה.

יש לבצע את התהליך הזה לכל בקשות הבדיקה של עיצוב. אין לאשר עיצובים שמשפיעים על Bazel אם הם לא באינדקס העיצוב.

האחריות של כותבי הביקורות המובילים

באחריותכם לקבל החלטות לגבי יישום של עיצוב בהמתנה. אם אין לך אפשרות לעשות זאת, עליך לזהות מי שהענקתו לו גישה (להקצות מחדש את יחסי הציבור של האדם שהעניק לו גישה), או להקצות את הבאג למנהל ב-Bazel להמשך טיפול.

בתהליך הבדיקה

1. ודאו שתהליך האיטרקציה של התגובה והעיצוב מתקדם באופן בונה.
2. לפני קבלת האישור, הקפידו לפתור חששות מבודקים אחרים.

לאחר אישור של כל כותבי הביקורות

1. יש לוודא שעבר שבוע אחד לפחות מאז ההודעה שפורסמה ברשימת הדיוור.
2. מוודאים שסטטוס יחסי הציבור מעדכן את הסטטוס.
3. מאשרים את יחסי הציבור שנשלחו על-ידי מחבר ההצעה.

דחיית עיצובים

1. לוודא שהמחבר של יחסי הציבור שולח יחסי ציבור; או לשלוח PR.
2. יח"צ מעדכן את סטטוס המסמך.
3. להוסיף תגובה למסמך ולהסביר מדוע לא ניתן לאשר את העיצוב במצבו הנוכחי, ולפרט את השלבים הבאים, אם יש כאלה (כגון "בדיקה חוזרת של הנחות לא חוקיות ושליחה מחדש").