אסטרטגיית גרסאות ה-Qiskit SDK
מספרי הגרסאות של Qiskit עוקבים אחר Semantic Versioning.
מספר הגרסה מורכב משלושה מרכיבים עיקריים: גרסה מג'ורית, גרסה מינורית ו גרסת תיקון (patch). לדוגמה, במספר גרסה X.Y.Z, X היא הגרסה המג'ורית, Y היא הגרסה המינורית, ו-Z היא גרסת התיקון.
שינויים שוברי תאימות (breaking API changes) שמורים לשחרורי גרסה מג'ורית. התקופה המינימלית בין שחרורי גרסה מג'ורית היא שנה אחת. גרסאות מינוריות מציגות תכונות חדשות ותיקוני באגים מבלי לשבור תאימות API, ומתפרסמות מעת לעת (כרגע כל שלושה חודשים) רק עבור הגרסה המג'ורית הנוכחית. גרסאות תיקון מספקות תיקונים לבאגים שזוהו בגרסה המינורית האחרונה של כל סדרת שחרורים הנתמכת באופן פעיל (כלומר, הגרסה המג'ורית). אנחנו תומכים לכל היותר בשתי סדרות שחרור בו-זמנית, דבר שמתרחש רק בתקופת החפיפה שלאחר שחרור גרסה מג'ורית חדשה, כפי שמתואר בפירוט רב יותר למטה.
לוח הזמנים לשחרורים
להלן לוח זמנים מוערך לשחרורים:
לקבלת לוח זמנים מעודכן לשחרורים, עיינו ברשימת אבני הדרך של פרויקט Qiskit ב-GitHub, שתמיד תכיל את תוכנית השחרורים הנוכחית.
עם שחרור גרסה מג'ורית חדשה, הגרסה המג'ורית הקודמת נתמכת למשך לפחות שישה חודשים עם תיקוני באגים בלבד, ושנה אחת לתיקוני אבטחה. במהלך תקופה זו מתפרסמות רק גרסאות תיקון עבור גרסה מג'ורית זו. גרסת תיקון סופית מתפרסמת כשהתמיכה מסתיימת, ואותו שחרור גם מתעד את סיום התמיכה בסדרת גרסה מג'ורית זו. חלון תמיכה ארוך יותר נדרש עבור הגרסה המג'ורית הקודמת כדי לתת לצרכני Qiskit שבהורדה ולמשתמשיהם הזדמנות להעביר את הקוד שלהם. ספריות שבהורדה שתלויות ב-Qiskit לא אמורות להעלות את גרסת Qiskit המינימלית הנדרשת לגרסה מג'ורית חדשה מיד לאחר שחרורה, מכיוון שבסיס המשתמשים של הספרייה זקוק לזמן להעברה לשינויי API החדשים. קיום חלון תמיכה מורחב לגרסת Qiskit המג'ורית הקודמת מעניק לפרויקטים שבהורדה זמן להבטיח תאימות עם הגרסה המג'ורית הבאה. פרויקטים שבהורדה יכולים לספק תמיכה בשתי סדרות שחרור בו-זמנית כדי לאפשר למשתמשיהם נתיב העברה.
למטרות semantic versioning, ה-API הציבורי של Qiskit נחשב לכל מודול, מחלקה, פונקציה או מתודה מתועדים שאינם מסומנים כפרטיים (עם קידומת קו תחתון _). עם זאת, ייתכנו חריגים מפורשים עבור APIs מתועדים ספציפיים. במקרים כאלה, APIs אלה יתועדו בבירור כממשקים שאינם עדיין נחשבים יציבים, ואזהרה גלויה למשתמש תוצג באופן פעיל בכל שימוש בממשקים לא יציבים אלה. בנוסף, במצבים מסוימים, ממשק המסומן כפרטי נחשב כחלק מה-API הציבורי. בדרך כלל זה מתרחש רק בשני מקרים: או הגדרת ממשק מופשט שבו מחלקות בנות מיועדות לדרוס/לממש מתודה פרטית כחלק מהגדרת מימוש הממשק, או מתודות ברמה נמוכה לשימוש מתקדם שיש להן ממשקים יציבים אך אינן נחשבות בטוחות לשימוש, מכיוון שהנטל על המשתמש לקיים את אינווריאנטי המחלקה/הבטיחות בעצמו (הדוגמה הקנונית לכך היא המתודה QuantumCircuit._append).
גרסאות Python הנתמכות, גרסת Rust המינימלית הנתמכת (לבנייה של Qiskit מהמקור), וכל תלויות חבילת Python (כולל גרסאות מינימום נתמכות של תלויות) שמשמשות את Qiskit אינן חלק מהבטחות התאימות לאחור ועשויות להשתנות בכל שחרור. רק שחרורי גרסה מינורית או מג'ורית יעלו דרישות מינימום לשימוש או לבנייה של Qiskit (כולל הוספת תלויות חדשות), אך תיקוני patch עשויים לכלול תמיכה בגרסאות חדשות של Python או תלויות אחרות. בדרך כלל הגרסה המינימלית של תלות מוגדלת רק כאשר גרסאות תלות ישנות יוצאות מתחום התמיכה, או כאשר לא ניתן לשמור על תאימות עם השחרור האחרון של התלות ועם הגרסה הישנה.
אסטרטגיית שדרוג
כאשר גרסה מג'ורית חדשה משוחררת, נתיב השדרוג המומלץ הוא לשדרג תחילה לגרסה המינורית האחרונה של הגרסה המג'ורית הקודמת. זמן קצר לפני גרסה מג'ורית חדשה, גרסה מינורית סופית תתפרסם. גרסה מינורית סופית זו X.Y+1.0.0 שווה ערך ל-X.Y.0 אך עם אזהרות ודחיות לכל שינויי API שנעשים בסדרת הגרסה המג'ורית החדשה.
לדוגמה, מיד לפני שחרור 1.0.0, שחרור 0.46.0 יתפרסם. שחרור 0.46.0 יהיה שווה ערך לשחרור 0.45.0 אך עם אזהרות דחייה נוספות שמתעדות את שינויי ה-API שנעשו כחלק מהשחרור 1.0.0. תבנית זו תשמש לכל שחרורי גרסה מג'ורית עתידיים.
משתמשי Qiskit צריכים לשדרג תחילה לגרסה מינורית סופית זו כדי לראות אזהרות דחייה ולהתאים את השימוש שלהם ב-Qiskit לפני ניסיון שחרור שעלול לשבור תאימות. הגרסה המג'ורית הקודמת תיתמך למשך לפחות שישה חודשים כדי לאפשר זמן מספיק לשדרוג. תבנית טיפוסית לניהול זה היא להצמיד את הגרסה המקסימלית כדי להימנע משימוש בסדרת הגרסה המג'ורית הבאה עד שאתם בטוחים בתאימות. לדוגמה, ציון qiskit<2 בקובץ requirements כאשר גרסת Qiskit המג'ורית הנוכחית היא 1 מבטיח שאתם משתמשים בגרסת Qiskit שאין בה שינויי API שוברי תאימות.
הצמדת הגרסה לפחות מהגרסה המג'ורית הבאה מבטיחה שתראו אזהרות דחייה לפני שחרור גרסה מג'ורית. ללא ההצמדה, pip מתקין את הגרסה החדשה ביותר הזמינה כברירת מחדל.
פורמט הסריאליזציה QPY תואם לאחור, כך שגרסה חדשה של Qiskit יכולה תמיד לטעון קובץ QPY שנוצר עם גרסה קודמת של Qiskit. עם זאת, הפורמט אינו תואם קדימה, ולכן, עקרונית, לא ניתן לטעון קבצי QPY שנוצרו עם גרסה חדשה יותר של Qiskit באמצעות שחרור ישן יותר. כדי להקל על העברת משתמשים בין שחרורי גרסה מג'ורית, הפונקציה qiskit.qpy.dump() תמיד תתמוך בלפחות גרסה חופפת אחת בין שחרורי X.0.0 ו-X-1.Y.0 (כאשר Y היא הגרסה המינורית האחרונה של אותה סדרה). הפרמטר qiskit.qpy.dump(..., version=...) יאפשר שמירת קבצי פורמט QPY שניתן לטעון על ידי שני הגרסאות המג'וריות מהשחרור החדש יותר. ראו פרטים נוספים ב-RFC 0020.
גרסאות מקדימות
לכל שחרור גרסה מינורית ומג'ורית, Qiskit מפרסם גרסאות מקדימות התואמות ל-PEP440. בדרך כלל אלה הם מועמדי שחרור בצורה X.Y.0rc1. שחרורי rc יהיו עם משטח API סופי וישמשו לבדיקת שחרור עתידי.
שימו לב שכאשר אחד מסיומות הגרסה המקדימה של PEP440 (כגון a, b, או pre) מתפרסמות, אין לו אותן הבטחות כמו שחרור rc, והוא רק שחרור תצוגה מקדימה. ה-API עשוי להשתנות בין גרסאות מקדימות אלה לבין השחרור הסופי עם אותו מספר גרסה. לדוגמה, ל-1.0.0pre1 עשוי להיות API סופי שונה מ-1.0.0.
גרסאות לאחר-שחרור
אם יש בעיות עם האריזה של שחרור, ייתכן שתתפרסם גרסת לאחר-שחרור כדי לתקן זאת. אלה יעקבו אחר הצורה X.Y.Z.1 כאשר המספר הרביעי מציין שזהו לאחר-שחרור הראשון של שחרור X.Y.Z. לדוגמה, לשחרור qiskit-terra (שם החבילה הישן של Qiskit) 0.25.2 הייתה בעיה כלשהי עם פרסום חבילת sdist, ולאחר-שחרור 0.25.2.1 תוקנה בעיה זו. הקוד היה זהה, ו-0.25.2.1 רק תיקן את בעיית האריזה לאותו שחרור.
כיצד תורמים יכולים לסמן דחיות
עיינו במדריך הדחיות במאגר Qiskit SDK לקבלת הוראות כיצד להוסיף דחיות לקוד המקור.