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

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

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

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

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

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

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

יצירת README

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

עם זאת, ה-CLI Firebase תומך בפקודת הנוחות הבאה כדי תיצור באופן אוטומטי קובץ 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 הוא הסקירה הכללית של התוסף, סוג של "שיווק". הדף הזה.

מהו התוכן בקובץ הזה?

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

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

מסוף Firebase">

מסוף Firebase">

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

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

יש שיטות מומלצות שכדאי ליישם?

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

Billing

This extension uses other Firebase or Google Cloud services which may have
  associated charges:

*   <list Google services / products that your extension uses>
*   <list Firebase services that your extension uses>
*   Cloud Secret Manager <if the extension uses secret params>
*   Cloud Functions

When you use Firebase Extensions, you're only charged for the underlying
resources that you use. A paid-tier billing plan is only required if the
extension uses a service that requires a paid-tier plan, for example calling to
a Google Cloud API or making outbound network requests to non-Google services.
All Firebase services offer a no-cost tier of usage.
[Learn more about Firebase billing.](https://firebase.google.com/pricing)

<Applicable info about billing implications for non-Google services, such as:>
Usage of this extension also requires you to have a <non-Google-service> account.
You are responsible for any associated costs with your usage of <non-Google-service>.

כתיבת קובץ POSTINSTALL

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

מה התוכן בקובץ הזה?

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

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

מסוף Firebase">

מסוף Firebase">

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

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

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

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

יש שיטות מומלצות שכדאי ליישם?

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

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

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

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

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

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

Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions_community#monitor)
of your installed extension, including checks on its health, usage, and logs.

תיעוד של האופן שבו מפעילים תוסף

בתיעוד למשתמשים של התוסף, צריך להסביר למשתמשים איך להפעיל את התוסף. ההוראות האלה יכולות להיות מפורטות לפי הצורך, אבל חשוב לזכור את השיטות המומלצות לכתיבת תיאור קובץ 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 מוצגים רק השינויים להיכנס לתוקף אם המשתמש ישלים את השדרוג.
• המאגר של קוד המקור של התוסף (בתוך ספריית התוסף).