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

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

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

تثبيت المحتوى مسبقًا في وحدة تحكّم 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، ستملأ وحدة التحكّم هذه الإشارات بالقيم الفعلية للنسخة المثبَّتة.

ملاحظة: بالنسبة إلى القيم التي يمكن أن تكون طويلة (مثل مسار قاعدة بيانات أو عنوان URL لدالة)، يُرجى الإشارة إلى المَعلمة أو المتغيّر في نهاية الجُمل والأقسام. تسهّل أفضل الممارسات هذه قراءة الجُمل في وحدة تحكّم 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)
	عنوان URL للدالة النهائية المنشورة، والتي يمكن لرمز العميل إرسال طلبات 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، خاصةً عند اختبار الإضافة لأول مرة. على سبيل المثال، لنفترض أنّ الإضافة تنشئ مستند Cloud Firestore جديدًا كلما تم إنشاء مستخدم Firebase Authentication جديد. يمكنك توجيه المستخدمين لاختبار نسخة مثبّتة من الإضافة عن طريق إضافة مستخدم جديد في Authentication يدويًا في وحدة التحكّم. ويمكنهم بعد ذلك الاطّلاع على المستند الجديد الذي تم إنشاؤه في قسم Cloud Firestore من وحدة التحكّم.

إضافة الرمز البرمجي من جهة العميل

يمكنك أيضًا، عند الاقتضاء، توجيه المستخدمين إلى كيفية إضافة رمز من جهة العميل لتفعيل الإضافة. يجب توجيه المستخدمين إلى المستندات الرسمية لواجهات برمجة التطبيقات التي سيحتاجون إلى استخدامها. يمكنك أيضًا تضمين نماذج تطبيقات أو نماذج برامج تجميع للعملاء لمساعدة المستخدمين في دمج الإضافة في تطبيقاتهم (يمكنك الاطّلاع على إضافة العدّاد الموزَّع كمثال).

الإضافات التي يتم تفعيلها من خلال طلبات HTTP

ليتمكّن المستخدمون من تفعيل دالة يتم تفعيلها من خلال طلب HTTP (وبالتالي تفعيل الإضافة)، عليك تزويدهم باسم الدالة التي تم نشرها أو عنوان URL الخاص بها.

لا يتطابق اسم الدالة النهائية المنشورة مع name الذي حدّدته في عنصر مورد الدالة ضمن extension.yaml. لإتاحة عمليات تثبيت متعددة للإضافة نفسها في مشروع، تعيد Firebase تسمية الدالة بهذا التنسيق: ext-extension-instance-id-function-name.

The following bullets are suggested boilerplate text to include in your extension's POSTINSTALL file. بعد التثبيت، تعرض وحدة تحكّم Firebase محتوى ملف POSTINSTALL وتملأ هذه المراجع بالقيم الفعلية التي تم ضبطها للنسخة المثبّتة. على سبيل المثال، إذا حدّدت دالة باسم yourFunction، يمكنك تضمين ما يلي (حسب الاقتضاء):

• بالنسبة إلى دوال HTTP onRequest

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

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