نشر الإضافة

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

قبل البدء

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

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

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

ويعني هذا في الوقت الحالي إتاحة رمز مصدر الإضافة في مستودع جيت هب العام.

هناك فوائد عديدة للتحميل من مصدر يمكن التحقق منه:

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

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

تتيح أدوات تطوير 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:

    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

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

  • باستخدام واجهة سطر الأوامر: يمكن للمستخدمين تثبيت الإضافة من خلال تمرير سلسلة رقم تعريف الإضافة إلى الأمر ext:install:

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

تحميل نسخة معدَّلة

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

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

  1. اختياري: يمكنك إضافة الرمز إلى مستودع Git متاح للجميع.

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

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id
    

    لن يُطلب منك هذه المرة تحديد مستودع GitHub أو الدليل الجذر للإضافة لأنّه سبق أن تم ضبطهما لإضافة. إذا كنت قد أعدت ضبط بنية المستودع أو انتقلت إلى مستودع جديد، يمكنك تغييرها باستخدام وسيطَي الأمر --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.

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

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