نشر الإضافة

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

قبل البدء

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

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

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

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

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

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

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

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

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

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

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

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

3. تحميل إصدار تجريبي إلى "مركز الإضافات" (انظر أدناه) يمكنك توزيع رابط التثبيت لاختبارات أوسع وتكراره من خلال تحميل المزيد من الإصدارات التجريبية حسب الضرورة.

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

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

• باستخدام واجهة سطر الأوامر: يمكن للمستخدمين تثبيت الإضافة من خلال تمرير سلسلة رقم تعريف الإضافة إلى الأمر 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، مع تحديد stable كمرحلة الإصدار:

   firebase ext:dev:upload your_publisher_id/your_extension_id
   

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

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

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

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

• لقد اختبرت الإضافة وعملية التثبيت بدقة.
• مستنداتك كاملة وصحيحة ويتم عرضها بشكل جيد في وحدة تحكُّم Firebase.
• يجب أن يعرّفك اسم الناشر وعلامتك التجارية بوضوح ودقة على أنّك الناشر
• يعبّر اسم الإضافة ووصفها ورمزها بوضوح ودقة عن الغرض من الإضافة.
• لقد طبَّقت علامات مفيدة ودقيقة.
• لقد أفصحتَ في extension.yaml عن جميع واجهات برمجة التطبيقات التي تستخدمها من Google وغير Google API، وجميع أنواع الأحداث التي تنبعث منها إضافتك.
• أنت تطلب الوصول إلى الأدوار اللازمة لوظيفة الإضافة، ولقد أوضحت بوضوح للمستخدمين سبب حاجتك إلى هذا الوصول.
• تم ترخيص ملفات المصدر بوضوح بموجب بنود 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. يستنسخ مستودع جيت هب ويتحقق من مرجع المصدر المحدد.

2. تثبِّت اعتماديات NPM من خلال تشغيل npm clean-install في كل دليل مصدر للدوال محدّد في extension.yaml (يُرجى الاطّلاع على sourceDirectory في موارد Cloud Function).

   لاحظ ما يلي:

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

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

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

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

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