migrations.json: שמירת תוכן קיים בשינוי מבנה

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

פרויקט חדש מתחיל ב־[]. אם גרסה 2 משנה את hero.title ל־hero.headline ומוסיפה את hero.eyebrow, אפשר לכתוב:

migrations.json

[
  {
    "fromVersion": 1,
    "toVersion": 2,
    "operations": [
      {
        "operation": "move",
        "from": "hero.title",
        "to": "hero.headline"
      },
      {
        "operation": "default",
        "path": "hero.eyebrow",
        "value": "Welcome"
      }
    ]
  }
]

הבנת הפעולות

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

המאפיינים fromVersion ו־toVersion מתייחסים ל־definition.json.version, ולא לגרסאות SDK או npm. גרסת היעד חייבת להיות גבוהה יותר, ונדרש מסלול מיגרציה מלא מההגדרה השמורה להגדרה החדשה.

עדכנו את כל חלקי השינוי

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

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

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

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