نشر الإضافة

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

قبل البدء

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

المصادر التي يمكن التحقّق منها

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

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

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

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

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

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

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

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 للإصدارات العلنية التي سيتم نشرها على 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

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

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

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

تحميل إصدار معدَّل

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

لتحميل تعديل:

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. إذا سبق لك نشر إصدار من إضافتك، سيؤدي تحميل إصدار جديد وثابت إلى إرسال الإضافة تلقائيًا للمراجعة.

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

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

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

• لقد اختبرت إضافتك وعملية التثبيت بدقة.
• الوثائق كاملة وصحيحة، ويتم عرضها بشكل جيد في Firebase console.
• يحدّد اسم الناشر وعلامته التجارية بوضوح ودقة أنّك الناشر.
• يمثّل اسم إضافتك ووصفها ورمزها بوضوح ودقة الغرض من إضافتك.
• لقد طبّقت علامات مفيدة ودقيقة.
• لقد أعلنت في 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.*

لا يتم إدراج الإصدارات المتوقّفة من الإضافة على Extensions Hub ولا يمكن تثبيتها. سيظهر للمستخدمين الذين ثبّتوا إصدارًا متوقّفًا على مشاريعهم رسالة تشجعهم على الترقية. وسيظل بإمكانهم استخدام الإضافة وإعادة ضبطها في هذه الأثناء.

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

لإلغاء عملية الإيقاف، استخدِم لوحة بيانات الناشر أو شغِّل الأمر 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 في موارد Cloud Functions).

   لاحظ ما يلي:

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

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

3. ينشئ الرمز عن طريق تشغيل npm run build في كل دليل مصدر دالة محدّد في extension.yaml.

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

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