במסמך הזה נסביר איך יוצרים פלאגין חדש. התהליך שמתואר במאמר הזה מיועד ליצירת יישומי פלאגין מאינטראקציה ישירה (First-Party), אבל אפשר להשתמש בו גם כמדריך ליצירת יישומי פלאגין של צד שלישי.
סקירה כללית על פלאגינים זמינה במאמר פלאגינים.
למבוא קצר ליצירת פלאגין, אפשר לעיין בשיחה בנושא יצירת פלאגין (2021).
נתונים מצד ראשון לעומת נתונים מצד שלישי
משתמש היעד של הפלאגין הוא מפתח שמוצא את הפלאגין ומשתמש בו דרך npm.
צוות Blockly תומך בפלאגינים מבית ומפרסם אותם ב-npm ברמת ההיקף @blockly. הם מיועדים לשימוש במגוון רחב של אפליקציות Blockly, והם יציבים וקלים לשימוש. הן מאוחסנות ב-blockly-samples. אפשר להשתמש בשדה להגדרת מהירות המנוע בפרויקטים רבים של רובוטיקה, והוא מתאים מאוד לפלאגין מהדומיין הנוכחי.
הפלאגינים של צד שלישי מתוחזקים ומתפרסמים באופן עצמאי. הן יכולות להיות מורכבות יותר, ניסיוניות יותר או שמוגדרות לטווח מצומצם יותר של אפליקציות Blockly. שדה לעריכת אובייקט ספציפי שמוגדר לפי הסכימה של מסד הנתונים עדיף כפלאגין של צד שלישי.
קריטריונים של צד ראשון
יישומי פלאגין של צד ראשון חייבים לעמוד בדרישות הבאות:
- עבודה בכל הפלטפורמות העיקריות, אלא אם צוות Blockly יעניק פטור.
- Chrome, Firefox, Safari, Edge
- יש לכם מחבר/ת שמוכנים לטפל בבאגים בשנה הראשונה.
- אין לבצע תיקון 'קוף' ב-Blockly.
- יש לכם ממשק API מוגדר ומתוועד בבירור.
- אסור להפעיל פונקציות פרטיות או פונקציות של חבילות מתוך הליבה של Blockly, אלא אם קיבלתם פטור מצוות Blockly.
- מותר לשנות את פונקציות החבילה בסוגי משנה שאתם מגדירים.
- אם אתם רוצים לקבל פטור, תוכלו לפנות אלינו בנושא ב-blockly-samples.
- יש בדיקות.
התהליך
הפלאגינים עוברים ארבעה שלבים: הצעה, דיון, הטמעה ופרסום.
הצעה
הפלאגין מתחיל כהצעה. כדי להציע פלאגין, צריך ליצור בעיה חדשה באמצעות התבנית בקשה לתכונה.
בנוסף למידע הבסיסי על בקשת התכונה, הצעה ל-Plugin צריכה לכלול:
- ממשק ה-API שהפלאגין יחשוף.
- ממשקי API שצריך להוסיף או לשנות ב-Blockly ליבה כדי לתמוך בפלאגין.
- צילומי מסך, קובצי GIF או מודלים ראשוניים, אם הפלאגין כולל תכונות של ממשק משתמש.
- הסבר למה צריך להשתמש בפלאגין של צד ראשון ולא בפלאגין של צד שלישי.
צוות Blockly בודק את ההצעות שמתקבלות, וסוגר את הבעיה או מסכים שהן יכולות להפוך ל-plugin טוב של צד ראשון.
קבוצת הדיון
בשלב הבא, הפלאגין עובר לשלב הדיון. השלב הזה כולל:
- הבהרה לגבי הפונקציונליות הרצויה.
- הבהרה לגבי ה-API של הפלאגין.
- תכנון ההטמעה.
- תכנון בדיקות.
- דיון בשינויים ב-API בליבה של Blockly.
- פירוק של יישומי פלאגין גדולים לשלבים של הטמעה.
- מתן שמות לפלאגין, בהתאם למוסכמות למתן שמות שלנו.
- אישור העמידה בכל הקריטריונים של צד ראשון.
בדרך כלל הדיון מתנהל בבעיה ב-GitHub. ככל שההיקף של הפלאגין קטן יותר, כך שלב הדיון יכול להתבצע מהר יותר. יישומי פלאגין גדולים יותר עשויים למשוך את תשומת הלב של הקהילה ולעורר דעות חזקות לגבי הפתרון הנכון. אם זה קורה בבעיה שלכם, מזל טוב! מצאתם משהו שאנשים מתעניינים בו.
המטרה היא שבסוף שלב הדיון, כל ההחלטות העיקריות לגבי העיצוב יתקבלו ותהיה רשימה ברורה של שלבי ההטמעה. יש לתעד את שניהם בתגובות לבעיה.
במהלך הדיון, יכול להיות שנחליט שהפלאגין צריך להיות פלאגין של צד שלישי, ולא לפרסם אותו במסגרת ההיקף @blockly. במקרה כזה, נסביר למה ונסגור את הבעיה.
בסיום הדיון, חבר בצוות Blockly מציין שהתכונה מוכנה להטמעה.
הטמעה
שלבי ההטמעה כוללים:
- הפעלת
npx @blockly/create-packageכדי להגדיר את הפלאגין ואת הספרייה שלו מתבנית. מידע נוסף - הטמעת הלוגיקה המרכזית של הפלאגין.
- הטמעת ממשק משתמש, אם יש צורך.
- בדיקת הפלאגין באמצעות Mocha.
- תיעוד הפלאגין, כולל
README.
אם הצעתם פלאגין שאושר להטמעה ואתם רוצים לעבוד עליו, תוכלו להגיב לבעיה ולשאול אם היא עדיין פתוחה לתרומות.
מספר שותפים יכולים לבצע את ההטמעה במקביל. אפשר להטמיע פלאגין בשיתוף פעולה ב-fork משלכם, או באמצעות בקשות משיכה למאגר הזה. אם אתם רוצים לשתף פעולה בפיתוח של תוסף במאגר הזה, תוכלו לבקש מצוות Blockly ליצור עבורכם הסתעפות של תכונה.
צריך להוסיף את הפלאגינים לקובץ gh-pages/index.md בהסתעפות master של blockly-samples. הפעולה הזו תגרום להם להופיע באתר הפלאגינים שלנו. פלאגינים של צד ראשון צריכים להפנות לדף הבדיקה שלהם. אפשר גם להוסיף לדף הזה יישומי פלאגין של צד שלישי, והם יכולים להפנות לקישור שבחר הבעלים שלהם, כמו הדגמה מתארחת או דף npm.
פרסום
ולבסוף, פרסום. צוות Blockly משתמש ב-Lerna כדי לנהל את הגרסאות והפרסום של כל הפלאגינים.
בכל יום חמישי אנחנו מפרסמים את כל הפלאגינים שהשתנו מאז הגרסה האחרונה שלהם. אם אתם רוצים שהשינוי יפורסם מוקדם יותר, ציינו זאת בבקשת המשיכה.
האתר של יישומי הפלאגין מתעדכן גם בכל פעם שמתפרסמים פלאגינים.
יש לסמן פלאגינים שעדיין לא מוכנים לפרסום ב-private ב-package.json שלהם. מצב כזה יכול לקרות אם הפלאגין מסתמך על שינוי ב-ליבה של Blockly שעדיין לא פורסם. הגרסה הבסיסית של Blockly מתפרסמת בשבוע האחרון של כל רבעון (פעם בשלוש חודשים).