نشر الإضافة

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

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

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

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

4. حمِّل الإصدار النهائي والثابت إلى "مركز الإضافات" (راجِع المعلومات أدناه) وأرسِله للمراجعة. إذا اجتازت الإضافة عملية المراجعة، سيتم نشرها على 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 للإصدارات المتاحة للجميع التي سيتم نشرها على Extensions Hub. سيؤدي تحميل إصدار 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

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

• باستخدام سطر الأوامر: يمكن للمستخدمين تثبيت الإضافة من خلال تمرير سلسلة 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 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.

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

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