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

يجب أن تحتوي كل إضافة على مستندات تعلم المستخدمين ما هي الإضافة وكيفية استخدامها.

الحد الأدنى من المستندات المطلوبة هو هذه المجموعة المكونة من ثلاثة ملفات 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)
• وصف موجز لأي آثار على الفوترة (يبدأ النص النموذجي)

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

• في صفحة الإضافة على 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" بعد أن يثبّت أحد المستخدمين إضافتك (في علامة بطاقة تفاصيل الإضافة المثبّتة)

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

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

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