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

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

الحد الأدنى من المستندات المطلوبة هو هذه المجموعة من ملفات 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 باستخدام هذا الأمر.

إضافة معلومات التثبيت

بعد كتابة ملف 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">

• في صفحة الإضافة على extensions.dev.
• مستودع رمز المصدر للإضافة (داخل دليل الإضافات)
• كجزء من ملف README الخاص بالإضافة (إذا كنت تستخدم 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">

وحدة تحكّم Firebase">

• في وحدة تحكّم Firebase بعد تثبيت المستخدم لإضافة Chrome (في بطاقة تفاصيل الإضافة المثبّتة)

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

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

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

ما هي أفضل الممارسات لحل هذه المشكلة؟

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

المعلمات والمتغيرات التي تتم الإشارة إليها

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