16.4. إصدار إضافتك

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

يُرجى إيلاء عناية خاصة للاقتراحات التالية:

16.4.1. البيانات الوصفية والأسماء

• تجنّب استخدام اسم شديد الشبه بأسماء إضافات موجودة

• إن كانت لإضافتك وظيفة مشابهة لإضافة موجودة، فيُرجى شرح الفروق في حقل About، ليعرف المستخدم أيهما يستخدم دون الحاجة إلى تثبيتها واختبارها

• تجنّب تكرار كلمة "plugin" في اسم الإضافة نفسه

• استخدم حقل description في البيانات الوصفية لوصف من سطر واحد، وحقل About لتعليمات أكثر تفصيلًا

• أدرج مستودع شيفرة ومتتبّع أخطاء وصفحة رئيسية؛ فهذا سيعزز إمكانية التعاون كثيرًا، ويمكن تحقيقه بسهولة شديدة باستخدام إحدى البنى التحتية المتاحة على الويب (GitHub، GitLab، Bitbucket، إلخ)

• اختر الوسوم بعناية: تجنّب الوسوم غير المفيدة (مثل vector) وفضّل تلك التي يستخدمها الآخرون بالفعل (راجع موقع الإضافات)

• أضف أيقونة مناسبة ولا تترك الأيقونة الافتراضية؛ راجع واجهة QGIS للاطلاع على النمط المقترح استخدامه

16.4.2. الشيفرة والمساعدة

• لا تُدرج الملفات المولَّدة (ui_*.py، resources_rc.py، ملفات المساعدة المولَّدة…) والأشياء غير المفيدة (مثل .gitignore) في المستودع

• أضف الإضافة إلى القائمة المناسبة (Vector، Raster، Web، Database)

• عند الاقتضاء (الإضافات التي تُجري تحليلات)، فكّر في إضافة الإضافة بوصفها إضافة فرعية لإطار المعالجة (Processing): سيتيح هذا للمستخدمين تشغيلها دفعيًا، ودمجها في مسارات عمل أكثر تعقيدًا، وسيعفيك من عبء تصميم واجهة

• أدرج توثيقًا ولو بالحد الأدنى، وبيانات نموذجية إن كانت مفيدة للاختبار والفهم.

16.4.3. مستودع إضافات Python الرسمي

تجد مستودع إضافات Python الرسمي على https://plugins.qgis.org/.

لاستخدام المستودع الرسمي عليك الحصول على معرّف OSGEO ID من بوابة OSGEO على الويب.

بعد رفع إضافتك، سيوافق عليها أحد أعضاء الفريق وستتلقى إشعارًا بذلك.

مهام قادمة:

إدراج رابط إلى وثيقة الحوكمة

16.4.3.1. الصلاحيات

طُبّقت القواعد التالية في مستودع الإضافات الرسمي:

• يستطيع كل مستخدم مسجّل إضافة إضافة جديدة

• يستطيع مستخدمو الفريق (staff) الموافقة على جميع إصدارات الإضافات أو رفضها

• المستخدمون الذين لديهم الصلاحية الخاصة plugins.can_approve تُعتمد الإصدارات التي يرفعونها تلقائيًا

• المستخدمون الذين لديهم الصلاحية الخاصة plugins.can_approve يستطيعون الموافقة على الإصدارات التي يرفعها آخرون ما داموا ضمن قائمة مالكي الإضافة

• لا يمكن حذف إضافة معينة أو تحريرها إلا من قِبل مستخدمي الفريق (staff) و مالكي الإضافة

• إن رفع مستخدم ليست لديه الصلاحية plugins.can_approve إصدارًا جديدًا، فإن إصدار الإضافة يصبح غير معتمد تلقائيًا.

16.4.3.2. إدارة الثقة

يستطيع أعضاء الفريق منح الثقة لمنشئي إضافات مختارين بتعيين الصلاحية plugins.can_approve عبر تطبيق الواجهة الأمامية.

يوفر عرض تفاصيل الإضافة روابط مباشرة لمنح الثقة لمنشئ الإضافة أو مالكيها.

16.4.3.3. التحقق

تُستورد البيانات الوصفية للإضافة ويُتحقق منها تلقائيًا من الحزمة المضغوطة عند رفع الإضافة.

إليك بعض قواعد التحقق التي يجب أن تكون على دراية بها عندما تريد رفع إضافة إلى المستودع الرسمي:

1. يجب أن يحتوي اسم المجلد الرئيسي الذي يضم إضافتك على أحرف ASCII فقط (A-Z و a-z) وأرقام والحرفين الشرطة السفلية (_) والشرطة (-)، كما لا يجوز أن يبدأ برقم

2. الملف metadata.txt إلزامي

3. يجب أن تكون جميع البيانات الوصفية الإلزامية المدرجة في جدول البيانات الوصفية موجودة

4. يجب أن يكون حقل البيانات الوصفية version فريدًا

5. يجب تضمين ملف ترخيص، محفوظ باسم LICENSE دون امتداد (أي ليس LICENSE.txt مثلًا)

16.4.3.4. بنية الإضافة

وفقًا لقواعد التحقق، يجب أن تكون للحزمة المضغوطة (.zip) لإضافتك بنية محددة لتجتاز التحقق بوصفها إضافة عاملة. وبما أن الإضافة ستُفك ضغطها داخل مجلد إضافات المستخدم، فيجب أن يكون لها مجلدها الخاص داخل ملف .zip كي لا تتداخل مع الإضافات الأخرى. الملفات الإلزامية هي: metadata.txt و __init__.py و LICENSE. لكن من الجيد أن يكون هناك README وبالطبع أيقونة تمثل الإضافة. فيما يلي مثال على الشكل الذي يمكن أن يبدو عليه plugin.zip.

plugin.zip
  pluginfolder/
  |-- i18n
  |   |-- translation_file_de.ts
  |-- img
  |   |-- icon.png
  |   |-- iconsource.svg
  |-- __init__.py
  |-- LICENSE
  |-- Makefile
  |-- metadata.txt
  |-- more_code.py
  |-- main_code.py
  |-- README
  |-- ui_Qt_user_interface_file.ui