يجب أن تحتوي كل إضافة على مستندات تعلم المستخدمين ما هي الإضافة وكيفية استخدامها.
الحد الأدنى من المستندات المطلوبة هو هذه المجموعة المكونة من ثلاثة ملفات 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.
- مستودع رمز المصدر للإضافة (داخل دليل الإضافات)
- كجزء من الملف التمهيدي للإضافة (إذا كنت تستخدم واجهة سطر الأوامر Firebase
الإبلاغ عن
)--markdown > README.md
لا يمكن لملفات PREINSTALL
الوصول إلى قيم المعلمات للإضافة، وبالتالي
يجب ألا تتوقع عرض مراجع المعلَمات بقيم فعلية.
ما هي بعض أفضل الممارسات؟
- أضِف المحتوى الكامل لملف
PREINSTALL
ضمن صفحة واحدة. إن أمكن - تقديم مستوى التفاصيل الذي يحتاج المستخدم النهائي إلى معرفته قبل تثبيت الإضافة
- يجب وضع تعليمات مفصّلة في ملف
POSTINSTALL
أو ملف آخر. الملفات التكميلية - وضِّح ما إذا كنت بصدد توفير أدوات أو نصوص برمجية أخرى لدعم الإضافة
كتابة ملف 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
.
مرجع لمتغيّرات مرتبطة بالدوال | الوصف | قيمة المتغيّر (تتم تعبئة الحقل تلقائيًا بواسطة Firebase بعد تثبيت الإضافة) |
---|---|---|
${function:function-name.location}
|
||
الموقع الجغرافي حيث يتم نشر الدالة |
مثال على القيمة:us-central1
|
|
${function:function-name.name}
|
||
اسم الدالة النهائية التي تم نشرها، والتي تشمل رقم تعريف المثيل الخاص بالإضافة |
تنسيق عام:
مثال على القيمة: |
|
${function:function-name.url}
(ينطبق على دوال HTTP فقط)
|
||
عنوان URL للدالة النهائية التي تم نشرها والتي يمكن لرمز العميل أن يؤدي إليها إجراء طلبات HTTP |
تنسيق عام:
مثال على القيمة: |
توثيق كيفية تشغيل إضافة
تحتاج في وثائق المستخدم للإضافة إلى إرشاد المستخدمين بشأن
كيفية تشغيل الإضافة. يمكن أن تكون هذه التعليمات مفصلة كما
يُعتبر ضروريًا، ولكن ضع في اعتبارك أفضل الممارسات لكتابة
ملف 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 وواجهة سطر الأوامر سوى التغييرات التي إذا أكمل المستخدم عملية الترقية.
- مستودع رمز المصدر للإضافة (داخل دليل الإضافات).