כתיבת נתוני גרסה

מסמך זה מיועד למומחים ב-Bazel.

תיאורי מחויבות ב-Bazel כוללים תג RELNOTES: ולאחריו הודעת הפצה. זה משמש את צוות Bazel כדי לעקוב אחר שינויים בכל גרסה ולכתוב הודעה על ההשקה.

סקירה

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

• אם השינוי מוסיף / מסיר / משנה את Bazel בדרך גלויה למשתמש, ייתכן שיהיה יתרון לאזכר אותו.

אם השינוי הוא משמעותי, יש לפעול לפי מדיניות מסמך העיצוב.

הנחיות

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

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

• יש להשתמש בגרשיים סביב קוד, סמלים, דגלים או כל מילה שמכילה קו תחתון.

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

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

• אם משהו הוצא משימוש או הוסר, יש להשתמש ב-"X הוצא משימוש" או ב-"X הוסר". לא "הוסר" או "הוסר".

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

• אם Bazel תומך עכשיו במשהו או לא תומך בו יותר, השתמש ב'Bazel תומך עכשיו / לא תומך יותר ב-X'.

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

• אל תבטיחו את הפונקציונליות הבאה. הימנעו מ "הסימון הזה יוסר" או מ "השינוי הזה ישתנה". הוא גורם לאי-ודאות. הדבר הראשון שתשאל את המשתמש הוא "מתי?" ואנחנו לא רוצים שהם יתחילו לדאוג שגרסאות ה-build הנוכחיות שלהם ייהרסו בזמן לא ידוע.

עבד

כחלק מתהליך הפרסום, אנחנו אוספים את תגי RELNOTES של כל התחייבות. אנחנו מעתיקים כל מסמך ב-Google Docs שבו אנחנו בודקים, עורכים ומארגנים את ההערות.

מנהל הגרסה שולח אימייל אל רשימת הדיוור bazel-dev. תורמי Bazel מוזמנים לתרום למסמך ולוודא שהשינויים שלהם משתקפים בצורה נכונה בהודעה.

לאחר מכן, ההודעה תישלח אל הבלוג Bazel, באמצעות מאגר הבלוג-bazel.