إنشاء مستندات المستخدم للإضافة

يجب أن تتضمّن كل إضافة مستندات تعليمية تشرح للمستخدمين وظيفة الإضافة وطريقة استخدامها.

الحد الأدنى من المستندات المطلوبة هو مجموعة ملفات Markdown الثلاثة التالية:

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

بالإضافة إلى ذلك، ننصحك أيضًا بإنتاج ما يلي:

• ملف README للمستودع العلني للإضافة
• برامج تعليمية وأدلة ومراجع أطول من حيث الشكل، يتم نشرها على موقعك الإلكتروني و ربطها بملف PREINSTALL.md

للتعرّف على بعض أفضل الممارسات والعبارات الشائعة والبنية، ننصحك بـ مراجعة الملفات المتاحة مع الإضافات Firebaseالرسمية.

إنشاء ملف README

يمكن أن يحتوي دليل الإضافة اختياريًا على ملف README. يُرجى العِلم أنّ الأمر firebase ext:dev:init لا يُنشئ ملفًا تلقائيًا.

مع ذلك، تتيح Firebase واجهة سطر الأوامر الأمر المريح التالي لـ إنشاء ملف README تلقائيًا يحتوي على محتوى تم جلبه من ملف extension.yaml وملف PREINSTALL.md:

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

يتم إنشاء جميع ملفات README لإضافات Firebase الرسمية باستخدام هذا الأمر.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 console">

Firebase console">

• في صفحة الإضافة على 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 أو إضافة رمز من جهة العميل (مثال)
• تعليمات عامة حول كيفية تجربة الـ إضافة المثبّتة على الفور (مثلاً، "انتقِل إلى وحدة التحكّم، ثم نفِّذ هذا الإجراء")
• معلومات أساسية حول كيفية تفعيل الإضافة، خاصةً الإضافات التي يتم تفعيلها من خلال طلبات HTTP
• تعليمات موجزة حول كيفية مراقبة الإضافة المثبّتة (ابدأ بنص نموذجي)

أين يظهر هذا المحتوى للمستخدم؟

Firebase console">

Firebase console">

• في Firebase console بعد أن يثبِّت المستخدم الإضافة (في الـ بطاقة التفاصيل الخاصة بالإضافة المثبّتة)

  • احرص على مراجعة طريقة عرض محتوى POSTINSTALL من خلال تثبيت الإضافة في مشروع فعلي.

• في مستودع رمز المصدر للإضافة (داخل دليل الإضافة)

يمكن لملفات POSTINSTALL الوصول إلى قيم المَعلمات والعديد من المتغيّرات المرتبطة بالدوال للإضافة. عند عرض محتوى POSTINSTALL في وحدة تحكّم Firebase، يتم عرض القيم الفعلية بدلاً من مراجع المَعلمات أو المتغيّرات. مزيد من المعلومات أدناه حول كيفية الإشارة إلى المَعلمات و المتغيّرات في ملف POSTINSTALL

ما هي أفضل الممارسات؟

• اجعل المحتوى الكامل لملف POSTINSTALL موجزًا ولكنه وصفي.
• قسِّم المحتوى باستخدام العناوين لفصل المهام أو المفاهيم المميّزة.
• ننصحك بنشر تعليمات مفصّلة لسير عمل أو مهمة معيّنة على موقعك الإلكتروني (مثال) أو في ملفات Markdown تكميلية ضمن مستودع الإضافة (مثال).
• أشِر إلى المَعلمات والمتغيّرات المرتبطة بالدوال حتى يرى المستخدم القيم التي تم ضبطها في سياق التعليمات

الإشارة إلى المَعلمات والمتغيّرات

بعد التثبيت، يعرض Firebase console محتوى ملف extension's POSTINSTALL الخاص بالإضافة. إذا أشرت إلى المَعلمات والمتغيّرات المرتبطة بالدوال (راجِع الجدول أدناه) في ملف POSTINSTALL، ستملأ وحدة التحكّم هذه المَراجع بالقيم الفعلية للمثيل المثبّت.

يمكنك الوصول إلى قيم المَعلمات التي تم ضبطها في ملف POSTINSTALL باستخدام البنية التالية: ${param:PARAMETER_NAME}

يمكنك أيضًا الإشارة إلى المتغيّرات التالية المرتبطة بالدوال في ملف POSTINSTALL فقط. تتيح Firebase هذه المتغيّرات لتسهيل تقديم إرشادات للمستخدمين بعد التثبيت. لا يمكن استخدامها إلا في ملف POSTINSTALL لأنّ قيم هذه المتغيّرات لا تتوفّر إلا بعد التثبيت.

في هذا الجدول، function-name هي قيمة حقل name في عنصر المورد للدالة ضمن extension.yaml.

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 console وواجهة سطر الأوامر، عندما يرقّي المستخدمون إلى إصدارات جديدة من الإضافة لا يعرض Firebase console وواجهة سطر الأوامر سوى التغييرات التي ستسري إذا أكمل المستخدم عملية الترقية.
• في مستودع رمز المصدر للإضافة (داخل دليل الإضافة)