نشر الإضافة

توضّح هذه الصفحة كيفية نشر إضافة على "مركز الإضافات".

قبل البدء

لنشر إضافة، عليك أولاً التسجيل كناشر للإضافات.

المصادر القابلة للتحقق

يجب أن يكون مصدر كل الإضافات المنشورة على "مركز الإضافات" قابلاً لإثبات ملكيته بشكل علني. بدلاً من تحميل رمز مصدر الإضافة مباشرةً إلى "مركز الإضافات"، يمكنك تحديد الموقع الجغرافي المصدر وسيقوم "مركز الإضافات" بتنزيله وإنشاءه من هناك.

ويعني ذلك حاليًا إتاحة رمز المصدر الخاص باإضافة على مستودع GitHub علني.

هناك العديد من المزايا لاستخدام مصدر يمكن التحقّق منه عند التحميل:

  • يمكن للمستخدمين فحص رمز المصدر لمراجعة معيّنة من الإضافة التي سيتم تثبيتها.
  • يمكنك التأكّد من تحميل ما تريد تحميله فقط، وليس مثلاً العمل الجاري أو الملفات العشوائية المتبقية من مرحلة التطوير.

دورة التطوير المقترَحة

تتيح أدوات تطوير Firebase Extensions تحميل إصدارات ما قبل الإصدار من إضافاتك، ما يسهّل عليك اختبار إضافاتك وعملية تثبيتها في البيئة نفسها التي سيتم طرحها فيها أخيرًا.

تتيح هذه الميزة إمكانية تنفيذ دورة تطوير على النحو التالي:

  1. يمكنك تطوير الإضافة وإجراء تكرارات عليها بسرعة باستخدام مجموعة أدوات المحاكاة في Firebase.

  2. اختبِر الإضافة في مشروع حقيقي من خلال تثبيتها من مصدر محلي:

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. تحميل إصدار تجريبي إلى Extensions Hub (راجِع الخطوات أدناه) وزِّع ملف بدء التثبيت لاختبار التطبيق على نطاق أوسع، وكرِّر الخطوات من خلال تحميل المزيد من الإصدارات التجريبية حسب الحاجة.

  4. حمِّل الإصدار النهائي والثابت إلى Extensions Hub (راجِع المعلومات أدناه) وأرسِله للمراجعة. إذا اجتازت الإضافة عملية المراجعة، سيتم نشرها على Extension Hub.

  5. عليك زيادة رقم الإصدار في extension.yaml وتكرار هذه الدورة للإصدار التالي من الإضافة.

تحميل إضافة جديدة

لتحميل إضافة للمرة الأولى:

  1. اختياري: عليك ربط الرمز البرمجي بمستودع GitHub عام.

  2. شغِّل الأمر ext:dev:upload في واجهة Firebase CLI:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    مصدر محلي

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    في طلب تنفيذ الأمر، يمكنك تحديد ما يلي:

    • الرقم التعريفي للناشر الذي سجّلته.

    • سلسلة رقم التعريف التي تحدِّد الإضافة أدخِل أسماء لإضافاتك باستخدام التنسيق التالي: firebase-product-description-of-tasks-performed. مثلاً: firestore-bigquery-export

    سيطلب منك الأمر تقديم معلومات إضافية:

    • في حال التحميل من GitHub:

      • عنوان URL الخاص بمستودع الإضافة في GitHub يُرجى العِلم أنّ أي مستودع يمكن أن يحتوي على إضافات متعددة ما دام لكل إضافة جذر فريد.

        عند تحميل إضافة جديدة للمرة الأولى، سيتم تسجيل المستودع كمصدر أساسي للإضافة.

      • الدليل في المستودع الذي يحتوي على إضافتك.

      • مرجع Git للالتزام الذي تريد إنشاء إصدار الإضافة منه يمكن أن يكون هذا الرمز تجزئة لعملية الإضافة أو علامة أو اسم فرع.

    • مرحلة إصدار الإصدار الذي تحمّله.

      إنّ مراحل alpha وbeta وrc (الإصدار المرشح للنشر) مخصّصة لتحميل الإصدارات التجريبية ليثبّتها المختبِرون. استخدم إحدى هذه المراحل في التحميل الأولي لإضافة جديدة.

      تُستخدَم المرحلة stable للإصدارات العلنية التي يتم نشرها على "مركز الإضافات". سيؤدي تحميل إصدار stable إلى بدء عملية مراجعة تلقائيًا، وفي حال اجتياز المراجعة، سيتم نشر الإضافة.

    يُرجى العِلم أنّه لا يمكنك تحديد رقم إصدار، لأنّ هذه القيمة تأتي من ملف extension.yaml. عند تحميل إصدار تجريبي للإضافة، يتم إلحاق المرحلة ورقم التحميل بالإصدار على سبيل المثال، إذا كان الإصدار extension.yaml يشير إلى الإصدار 1.0.1 وحمّلت إصدارًا مرشحًا للإصدار، سيؤدي ذلك إلى الإصدار 1.0.1-rc.0. وسيؤدي تحميل إصدار مرشح آخر للإصدار نفسه إلى زيادة العدد تلقائيًا، ما يؤدي إلى الإصدار 1.0.1-rc.1، وما إلى ذلك.

بعد تحميل إصدار تجريبي من الإضافة، يمكنك مشاركتها مع الآخرين لاختبارها. يمكن للمستخدمين تثبيت إضافتك بطريقتَين:

  • باستخدام وحدة التحكّم: يمكن للمستخدمين تثبيت الإضافة بالنقر على رابط بالتنسيق التالي:

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    يمكنك مشاركة الرابط المباشر مع المختبِرين.

  • باستخدام سطر الأوامر: يمكن للمستخدمين تثبيت الإضافة من خلال تمرير سلسلة ‎extension ID إلى الأمر ext:install:

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

تحميل نسخة محدثة

بعد تحميل الإصدار الأول من إحدى الإضافات، يمكنك تحميل تعديلات لحلّ المشاكل أو إضافة ميزات أو الانتقال إلى مرحلة الإصدار. عند تحميل إصدار جديد، سيُطلب من المستخدمين الذين لديهم إصدار قديم من الإضافة تثبيت الإصدار الجديد في وحدة تحكّم Firebase.

لتحميل تحديث، اتّبِع الخطوات التالية:

  1. اختياري: عليك ربط الرمز البرمجي في مستودع Git متاح للجميع.

  2. شغِّل الأمر ext:dev:upload في واجهة سطر الأوامر في Firebase:

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    هذه المرة لن يُطلب منك تحديد مستودع جيت هب أو الدليل الجذري للإضافة إذ تم ضبطهما مسبقًا للإضافة. إذا كنت قد أعدت صياغة بنية المستودع أو نقلته إلى مستودع جديد، يمكنك تغييرها باستخدام المَعلمتَين--root و--repo.

    مصدر محلي

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

إرسال طلب تمديد لنشر المحتوى

عندما تكون مستعدًا لإصدار الإضافة علنًا:

  1. احفظ الرمز البرمجي في مستودع Git متاح للجميع. (مطلوب للإصدارات المُتاحة للجميع).

  2. نفِّذ الأمر ext:dev:upload في واجهة Firebase CLI، مع تحديد stable كأحد مراحل الإصدار:

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. إذا سبق لك نشر إصدار من الإضافة، سيؤدي تحميل إصدار جديد ومستقر إلى إرسال الإضافة تلقائيًا للمراجعة.

    إذا حمّلت الإصدار الأول من الإضافة الثابت، ابحث عن الإضافة في لوحة بيانات الناشر، وانقر على النشر في مركز الإضافات.

بعد إرسال الطلب، قد تستغرق المراجعة بضعة أيام. في حال الموافقة على الإضافة، سيتم نشرها في "مركز الإضافات". في حال الرفض، ستتلقّى رسالة توضّح سببه، ويمكنك بعد ذلك معالجة المشاكل التي تم الإبلاغ عنها وإعادة إرسال العينة لمراجعتها.

لتسريع عملية المراجعة وزيادة فرص اجتياز المراجعة في المرة الأولى، يُرجى التحقّق مما يلي قبل الإرسال:

  • لقد اختبرت الإضافة وعملية التثبيت بدقة.
  • مستنداتك كاملة وصحيحة ويتم عرضها بشكل جيد في وحدة تحكُّم Firebase.
  • يشير اسم الناشر وعلامته التجارية إلى هويتك بوضوح ودقة بصفتك الناشر.
  • أن يعبّر اسم الإضافة ووصفها ورمزها بوضوح ودقة عن الغرض من الإضافة
  • لقد طبَّقت علامات مفيدة ودقيقة.
  • لقد أفصحت في extension.yaml عن جميع واجهات برمجة التطبيقات التي تستخدمها من Google وغير التابعة لها، وجميع أنواع الأحداث التي تُرسِلها الإضافة.
  • أنت تطلب الوصول إلى الأدوار اللازمة لوظيفة الإضافة، ولقد أوضحت بوضوح للمستخدمين سبب حاجتك إلى هذا الوصول.
  • أن تكون ملفات المصدر مرخّصة بوضوح بموجب أحكام Apache-2.0

إدارة الإضافات التي تم تحميلها ونشرها

إدراج الإضافات التي تم تحميلها

لإدراج الإضافات التي حمّلتها ضمن رقم التعريف الخاص بك بصفتك ناشرًا، نفِّذ أحد الإجراءَين التاليَين:

لوحة بيانات الناشر

ويمكنك الاطّلاع عليها في لوحة بيانات الناشر.

Firebase CLI

نفِّذ الأمر ext:dev:list:

firebase ext:dev:list your_publisher_id

الاطّلاع على استخدام الإضافات التي حمّلتها

لعرض استخدام الإضافات التي حمّلتها ضمن الرقم التعريفي للناشر، نفِّذ أحد الإجراءات التالية:

لوحة بيانات الناشر

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

Firebase CLI

نفِّذ الأمر ext:dev:usage:

firebase ext:dev:usage your_publisher_id

إيقاف إصدار إضافة نهائيًا

في مرحلة ما، قد تريد إيقاف إصدار قديم من الإضافة نهائيًا. على سبيل المثال، إذا طرحت إصدارًا جديدًا يعمل على إصلاح خطأ بالغ الأهمية أو يحدِّث التبعية باستخدام تحديث أمان مهم، من المهم منع المستخدمين الجدد من تثبيت إصدار قديم وتشجيع المستخدمين الحاليين على الترقية.

لإيقاف إصدار من إضافة نهائيًا، نفِّذ أحد الإجراءات التالية:

لوحة بيانات الناشر

  1. في لوحة بيانات الناشر، انقر على الإضافة لفتح صفحة عرض التفاصيل الخاصة بها.
  2. اختَر الإصدار الذي تريد إيقافه نهائيًا.
  3. انقر على إيقاف الإصدار نهائيًا.

Firebase CLI

نفِّذ الأمر ext:dev:deprecate:

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

يمكنك تحديد إصدار واحد أو نطاق إصدارات. أمثلة:

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

لا يتم إدراج الإصدارات المتوقّفة نهائيًا من الإضافة في "مركز الإضافات" ولا يمكن تثبيتها. سيظهر للمستخدمين الذين تم تثبيت إصدار قديم من الإضافة في مشاريعهم رسالة تدعوهم إلى الترقية، وسيظل بإمكانهم استخدام الإضافة وإعادة ضبطها في الوقت الحالي.

إذا تم إيقاف كل إصدار من الإضافة نهائيًا، سيتم اعتبار الإضافة متوقفة نهائيًا وسيتم إلغاء إدراجها من "مركز الإضافات". سيؤدي تحميل إصدار جديد من إضافة متوقّفة نهائيًا إلى بدء عملية مراجعة تلقائيًا، وبعد الموافقة عليها، سيتم نشرها في "مركز الإضافات" مرة أخرى.

لإلغاء إيقاف ميزة نهائيًا، استخدِم لوحة بيانات الناشر أو نفِّذ الأمر ext:dev:undeprecate في واجهة Firebase CLI:

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

الملحق: تحديد أخطاء الإصدار وحلّها

عند تحميل الإضافة، تنشئ الخلفية أولاً رمز المصدر باستخدام الخطوات التالية:

  1. تستنسخ هذه الوظيفة مستودع GitHub وتتحقّق من مرجع المصدر المحدّد.

  2. تثبيت متطلّبات NPM من خلال تشغيل npm clean-install في كل دليل مصدر دالة محدّد في extension.yaml (راجِع sourceDirectory في موارد وظائف السحابة الإلكترونية).

    لاحظ ما يلي:

    • يجب أن يحتوي كل ملف package.json على ملف package-lock.json مقابل. لمزيد من المعلومات، يُرجى الاطّلاع على npm-ci.

    • لن يتم تشغيل النصوص البرمجية لما بعد التثبيت أثناء تثبيت التبعية. إذا كان إصدار رمز المصدر يعتمد على النصوص البرمجية بعد التثبيت، عليك إعادة ضبط هذا الإصدار قبل التحميل.

  3. تُنشئ رمزك البرمجي من خلال تشغيل npm run build في كل ملف برمجي تابع للدالة في الدليل المحدّد في extension.yaml.

سيتم حفظ دليل الجذر للإضافة فقط في حِزمة الإضافة النهائية التي ستتم مشاركتها.

إذا ظهرت لك أخطاء في عملية الإنشاء أثناء تحميل الإضافة، كرِّر الخطوات المذكورة أعلاه محليًا في دليل جديد إلى أن تختفي الأخطاء، ثم حاوِل التحميل مرة أخرى.