צור תיעוד משתמש עבור התוסף שלך

לכל תוסף חייב להיות תיעוד שמלמד את המשתמשים מה התוסף עושה וכיצד להשתמש בו.

התיעוד המינימלי, הנדרש, הוא קבוצה זו של שלושה קובצי סימון:

  • PREINSTALL.md
  • POSTINSTALL.md
  • CHANGELOG.md

בנוסף, כדאי לשקול גם לייצר:

  • קובץ README עבור המאגר הציבורי של התוסף.
  • מדריכים, מדריכים והתייחסויות ארוכות יותר שפורסמו באתר האינטרנט שלך ומקושרות ב- PREINSTALL.md שלך.

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

יצירת README

ספריית ההרחבות שלך יכולה להכיל אופציונלי README. שים לב שהפקודה firebase ext:dev:init לא יוצרת עבורך אחת אוטומטית.

עם זאת, ה-Firebase CLI תומך בפקודת הנוחות הבאה ליצור אוטומטית קובץ README המכיל תוכן שנשלף מקובץ extension.yaml שלך ומקובץ PREINSTALL.md שלך:

firebase ext:info ./path/to/extension --markdown > README.md

כל קובצי ה-README עבור ההרחבות הרשמיות של Firebase נוצרים באמצעות פקודה זו.

הוסף מידע על התקנה

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

---

## 🧩 Install this extension

### Console

[![Install this extension in your Firebase project](https://www.gstatic.com/mobilesdk/210513_mobilesdk/install-extension.png "Install this extension in your Firebase project")][install-link]

[install-link]: https://console.firebase.google.com/project/_/extensions/install?ref=publisher_id/extension_name

### Firebase CLI

```bash
firebase ext:install publisher_id/extension_name --project=[your-project-id]
```

> Learn more about installing extensions in the Firebase Extensions documentation:
> [console](https://firebase.google.com/docs/extensions/install-extensions?platform=console),
> [CLI](https://firebase.google.com/docs/extensions/install-extensions?platform=cli)

---

כתיבת קובץ PREINSTALL

קובץ ה- PREINSTALL הוא הסקירה הכללית של התוסף שלך, סוג של דף "שיווק".

איזה תוכן יש בקובץ הזה?

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

היכן מוצג תוכן זה למשתמש?

תמונה של תוכן להתקנה מראש במסוף Firebase
התקן מראש תוכן במסוף Firebase

תמונה גדולה של תוכן להתקנה מראש במסוף Firebase

  • בעמוד התוסף ב- extensions.dev .
  • מאגר קוד המקור שלך עבור התוסף שלך (בתוך ספריית ההרחבות)
  • כחלק מה-README של התוסף (אם אתה משתמש ב-Firebase CLI --markdown > README.md )

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

מהן כמה שיטות עבודה מומלצות?

  • שמור את התוכן המלא של קובץ ה- PREINSTALL מתחת לדף אחד , אם אפשר
  • ספק את רמת הפירוט שמשתמש קצה צריך לדעת לפני התקנת התוסף
  • שים הוראות מפורטות בקובץ POSTINSTALL או בקבצים משלימים אחרים
  • ציין בקצרה אם אתה מספק כלים או סקריפטים אחרים לתמיכה בהרחבה

כתיבת קובץ POSTINSTALL

קובץ POSTINSTALL הוא דף ההדרכה המפורט של התוסף שלך לאחר ההתקנה.

איזה תוכן יש בקובץ הזה?

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

היכן מוצג תוכן זה למשתמש?

תמונה של תוכן לאחר ההתקנה במסוף Firebase
תוכן לאחר התקנה במסוף Firebase

תמונה גדולה של תוכן לאחר ההתקנה במסוף Firebase

  • במסוף Firebase לאחר שמשתמש מתקין את התוסף שלך (בכרטיס הפרטים של התוסף המותקן)

  • מאגר קוד המקור שלך עבור התוסף שלך (בתוך ספריית ההרחבות)

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

מהן כמה שיטות עבודה מומלצות?

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

התייחסות לפרמטרים ומשתנים

לאחר ההתקנה, מסוף Firebase מציג את התוכן של קובץ POSTINSTALL של התוסף. אם אתה מתייחס לפרמטרים ומשתנים הקשורים לפונקציות (ראה טבלה למטה) בקובץ POSTINSTALL שלך, המסוף מאכלס הפניות אלה בערכים בפועל עבור המופע המותקן.

גש לערכי פרמטרים מוגדרים בקובץ POSTINSTALL באמצעות התחביר הבא: ${param: PARAMETER_NAME }

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

בטבלה זו, function-name הוא הערך של שדה name באובייקט המשאב של הפונקציה בתוך extension.yaml .

התייחסות למשתנה הקשור לפונקציה תיאור ערך משתנה (מאוכלס אוטומטית על ידי Firebase לאחר התקנת התוסף)
${function: function-name .location}
מיקום שבו הפונקציה נפרסת ערך לדוגמה:
us-central1
${function: function-name .name}
שם הפונקציה הסופית שנפרסה , הכוללת את מזהה המופע של התוסף

פורמט כללי:
ext- extension-instance-id - function-name

ערך לדוגמה:
ext-my-awesome-extension-6m31-yourFunctionName

${function: function-name .url} (מתאים רק לפונקציות HTTP)
כתובת האתר של הפונקציה הסופית שנפרסה , שאליה קוד הלקוח יכול לבצע בקשות HTTP

פורמט כללי:
https:// deployment-location - project-id .cloudfunctions.net/ name-of-final-deployed-function

ערך לדוגמה:
https://us-central1-project-123.cloudfunctions.net/ext-my-awesome-extension-6m31-yourFunctionName

תיעוד כיצד להפעיל הרחבה

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

כתיבת קובץ CHANGELOG

איזה תוכן יש בקובץ הזה?

לכל הרחבה חייב להיות קובץ CHANGELOG.md שמתעד את השינויים הכלולים בכל גרסה חדשה של ההרחבה שלך שאתה מפרסם. שים כל גרסה תחת כותרת רמה 2 ( ## ); אחרת, אתה יכול להשתמש בכל עיצוב של Markdown שתרצה.

הדוגמה הבאה היא קטע מאחת ההרחבות הרשמיות:

## Version 0.1.3

feature - Support deletion of directories (issue #148).

## Version 0.1.2

feature - Add a new param for recursively deleting subcollections in Cloud
Firestore (issue #14).

fixed - Fixed "cold start" errors experienced when the extension runs after a
period of inactivity (issue #48).

## Version 0.1.1

Initial release of the _Delete User Data_ extension.

היכן מוצג התוכן הזה למשתמש?

  • במסוף Firebase וב-CLI, כאשר משתמשים משדרגים לגרסאות חדשות של התוסף שלך. מסוף Firebase ו-CLI מציגים רק את השינויים שייכנסו לתוקף אם המשתמש היה משלים את השדרוג.
  • מאגר קוד המקור של התוסף שלך (בתוך ספריית ההרחבות).