نشر الإضافة

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

قبل البدء

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

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

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

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

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

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

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

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

وتجعل هذه الإمكانية دورة تطوير مثل ما يلي:

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

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

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

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

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

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

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

• باستخدام سطر الأوامر: يمكن للمستخدمين تثبيت الإضافة من خلال تمرير سلسلة ‎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 وغير التابعة لـ 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 في كل ملف ملف ملف directory مصدر دالة محدد في extension.yaml.

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

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