ایجاد کردن مستندات کاربر برای افزونه

هر افزونه باید مستنداتی داشته باشد که به کاربران آموزش دهد افزونه چه کاری انجام می‌دهد و چگونه باید از آن استفاده کرد.

حداقل اسناد موردنیاز این مجموعه از سه فایل نشان‌گذاری است:

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

علاوه‌براین، باید تولید موارد زیر را نیز درنظر بگیرید:

• فایل README برای مخزن عمومی افزونه.
• آموزش‌ها، راهنماها، و مراجع طولانی‌تر که در وب‌سایت خودتان منتشر شده‌اند و در PREINSTALL.md شما پیوند داده شده‌اند.

برای آشنایی با برخی‌از روال‌های مطلوب و عبارت‌بندی و ساختار رایج، توصیه می‌کنیم فایل‌های موجود با افزونه‌های Firebase رسمی را مرور کنید.

درحال ایجاد «مرا بخوان»

دایرکتوری افزونه شما می‌تواند به‌صورت اختیاری حاوی یک 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 یا سایر فایل‌های تکمیلی قرار دهید
• اگر ابزارها یا اسکریپت‌های دیگری برای پشتیبانی از افزونه ارائه می‌دهید، به‌طور خلاصه ذکر کنید

نوشتار تکراری مفید PREINSTALL

توصیه می‌کنیم تا حد امکان از متن استاندارد زیر استفاده کنید، زیرا برای افزونه شما مناسب است. چند نمونه ارائه کرده‌ایم، اما مهم‌ترین نکته این است که مطمئن شوید همه سرویس‌های صورت‌حساب‌شده Google و غیرGoogle فهرست شده باشند.

می‌توانید از منابع زیر برای پیدا کردن جزئیات صحیح قیمت‌گذاری محصول استفاده کنید:

• فهرست قیمت محصول Google Cloud
• نمای کلی قیمت‌گذاری Firebase

برای همه افزونه‌ها، این بخش را اضافه کنید تا به کاربران کمک کنید پیامدهای صورت‌حساب را درک کنند:

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 یا افزودن کد سمت کارخواه (نمونه)
• دستورالعمل‌های عمومی درباره نحوه امتحان کردن فوری افزونه نصب‌شده (برای مثال، «به کنسول بروید، سپس این کار را انجام دهید»)
• اطلاعات پایه درباره نحوه راه‌اندازی افزونه، به‌ویژه برای افزونه‌های راه‌اندازی‌شده با درخواست HTTP
• دستورالعمل‌های مختصر درباره نحوه نظارت بر افزونه نصب‌شده (با نوشتار تکراری شروع کنید)

این محتوا کجا به کاربر نشان داده می‌شود؟

کنسول Firebase">

محتوای پس‌از نصب در Firebase کنسول

کنسول Firebase">

• در کنسول Firebase پس‌از اینکه کاربر افزونه شما را نصب کرد (در کارت جزئیات افزونه نصب‌شده)

  • حتماً نمایش محتوای POSTINSTALL را با نصب افزونه‌تان در پروژه واقعی مرور کنید.

• مخزن کد منبع شما برای افزونه‌تان (درون فهرست راهنمای افزونه)

فایل‌های POSTINSTALL می‌توانند به مقادیر پارامتر و چندین متغیر مرتبط با تابع برای افزونه دسترسی داشته باشند. وقتی محتوای POSTINSTALL در کنسول Firebase نمایش داده می‌شود، مقادیر واقعی به‌جای ارجاع‌های متغیر یا پارامتر نمایش داده می‌شود. در زیر درباره نحوه ارجاع دادن به پارامترها و متغیرها در فایل POSTINSTALL بیشتر بدانید.

برخی‌از روال‌های مطلوب چیست؟

• محتوای کامل فایل POSTINSTALL را مختصر اما توصیفی نگه دارید.
• محتوا را بااستفاده از عنوان‌ها بخش‌بندی کن تا تکالیف یا مفاهیم متمایز از هم جدا شوند.
• دستورالعمل‌های دقیق برای گردش کار یا تکلیف خاصی را در وب‌سایتتان (نمونه) یا در فایل‌های markdown تکمیلی در مخزن افزونه (نمونه) منتشر کنید.
• پارامترهای مرجع و متغیرهای مرتبط با تابع تا کاربر مقادیر پیکربندی‌شده آن‌ها را در بافت دستورالعمل‌ها ببیند

ارجاع دادن به پارامترها و متغیرها

پس‌از نصب، کنسول Firebase محتوای فایل POSTINSTALL افزونه را نمایش می‌دهد. اگر در فایل POSTINSTALL به پارامترها و متغیرهای مربوط به تابع (جدول زیر را ببینید) ارجاع دهید، کنسول این ارجاع‌ها را با مقادیر واقعی برای نمونه نصب‌شده پر می‌کند.

نکته: برای مقادیری که می‌توانند طولانی باشند (مانند مسیر پایگاه داده یا نشانی وب تابع)، به پارامتر یا متغیر در انتهای جملات و بخش‌ها ارجاع دهید. این روال مطلوب باعث می‌شود خواندن جملات در کنسول Firebase آسان‌تر شود، وقتی محتوای فایل 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

توصیه می‌کنیم تا حد امکان از متن استاندارد زیر استفاده کنید، زیرا برای افزونه شما مناسب است.

برای همه افزونه‌ها، بخش زیر را اضافه کنید تا به کاربران کمک کنید افزونه نصب‌شده‌شان را پایش کنند:

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 را به‌خاطر داشته باشید. برای راهنمایی درباره نحوه ارائه این دستورالعمل‌ها، بخش زیر را که مربوط به افزونه شما است ازهم باز کنید.

افزونه‌های راه‌اندازی‌شده با رویداد پس‌زمینه

کاربران شما می‌توانند افزونه راه‌اندازی‌شده با رویداد پس‌زمینه را به روش‌های مختلفی راه‌اندازی کنند، بسته به محصولات درگیر.

تغییرات را مستقیماً در کنسول اعمال کنید

می‌توانید به کاربران خود آموزش دهید که تغییرات راه‌انداز افزونه را مستقیماً در کنسول Firebase اعمال کنند، به‌ویژه برای آزمایش اولیه افزونه شما. برای مثال، فرض کنید افزونه شما هربار که کاربر Firebase Authentication جدیدی ایجاد می‌شود، سند Cloud Firestore جدیدی ایجاد می‌کند. می‌توانید به کاربرانتان آموزش دهید تا با افزودن دستی کاربر Authentication جدید در کنسول، نمونه نصب‌شده افزونه‌تان را آزمایش کنند. سپس می‌توانند سند جدید ایجادشده را در بخش Cloud Firestore کنسول مشاهده کنند.

افزودن کد سمت کارخواه

درصورت لزوم، می‌توانید به کاربران خود آموزش دهید که چگونه کد سمت کارخواه را برای راه‌اندازی افزونه شما اضافه کنند. باید کاربران را به اسناد رسمی میاناهای برنامه‌سازی کاربردی که باید استفاده کنند هدایت کنید. همچنین می‌توانید برنامه‌های نمونه یا نمونه‌های مشتری کامپایل‌شده را اضافه کنید تا به کاربران کمک کنید افزونه را در برنامه‌شان ادغام کنند (برای نمونه، به افزونه شمارنده توزیع‌شده مراجعه کنید).

افزونه‌های راه‌اندازی‌شده با درخواست HTTP

برای اینکه کاربران شما بتوانند تابع راه‌اندازی‌شده با درخواست HTTP (و درنتیجه افزونه) را راه‌اندازی کنند، باید نام یا نشانی وب تابع مستقرشده را به آن‌ها ارائه دهید.

نام تابع نهایی مستقرشده با name که در شیء منبع تابع در extension.yaml مشخص کرده‌اید یکسان نیست. برای سازگار کردن نصب‌های متعدد از یک افزونه در پروژه، Firebase نام تابع را به این قالب تغییر می‌دهد: ext-extension-instance-id-function-name.

نکته‌های زیر نوشتار قالبی پیشنهادی برای گنجاندن در فایل POSTINSTALL افزونه‌تان است. پس‌از نصب، کنسول Firebase محتوای فایل POSTINSTALL را نمایش می‌دهد و این ارجاع‌ها را با مقادیر پیکربندی‌شده واقعی برای نمونه نصب‌شده پر می‌کند. برای مثال، اگر تابعی به‌نام yourFunction تعریف کرده‌اید، می‌توانید موارد زیر را (درصورت لزوم) اضافه کنید:

• برای توابع اچ‌تی‌تی‌پی onRequest

  To trigger this extension, make a request to or visit the following URL:
  **`${function:yourFunction.url}`**.
  

• برای توابع قابل‌فراخوانی اچ‌تی‌تی‌پی (onCall)

  This extension is implemented as an HTTP callable function. To call it from your client app,
  follow the instructions in the
  [callable functions documentation](https://firebase.google.com/docs/functions/callable#call_the_function).
  The name of the function to call is **`${function:yourFunction.name}`**,
  and its region is **`${function:yourFunction.location}`**.
  

مهم: قبل‌از اینکه کاربران شما بتوانند از افزونه راه‌اندازی‌شده با درخواست HTTP استفاده کنند، باید توابع مستقرشده برای افزونه را به‌طور عمومی دردسترس قرار دهند. دستورالعمل‌های دقیق برای ارائه به کاربران در نمونه‌های متن استاندارد در بالا آمده است.

نوشتن فایل CHANGELOG

چه محتوایی در این فایل وجود دارد؟

هر افزونه باید یک فایل CHANGELOG.md داشته باشد که تغییرات موجود در هر نسخه جدید از افزونه شما را که منتشر می‌کنید، مستند کند. هر نسخه را زیر عنوان سطح ۲ (##) قرار دهید؛ درغیراین‌صورت، می‌توانید از هر قالب‌بندی 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 فقط تغییراتی را نمایش می‌دهند که درصورت تکمیل ارتقا توسط کاربر اعمال می‌شوند.
• مخزن کد منبع افزونه شما (درون دایرکتوری افزونه).