CocoaPods Trunk: ما هو، نشر المكتبات عبر Trunk

ما هو CocoaPods Trunk؟

CocoaPods Trunk هي بنية تحتية للخادم تم إطلاقها في عام 2015 للنشر المركزي لمكتبات pod. قبل Trunk، كان يتم توزيع كل pod عبر مستودع Git: كان على المطور إنشاء مستودع عام وإضافة ملف podspec وإرسال Pull Request إلى المستودع المركزي CocoaPods/Specs. تطلب هذا النهج مراجعة يدوية وتسبب في تأخيرات عند نشر التحديثات.

حل Trunk هذه المشاكل بتوفير API موحد للنشر والتحديث وإدارة ال pods. تشمل الخدمة أربعة مكونات رئيسية:

• المصادقة — التسجيل مع تأكيد البريد الإلكتروني وإدارة رموز الجلسة. يحصل كل مطور على رمز فريد مرتبط بحسابه وأجهزته.
• التحقق — فحص تلقائي لملف podspec قبل النشر، بما في ذلك التحليل النحوي وفحص التبعيات والتحقق من توافق المنصات.
• الاستضافة — تخزين البيانات الوصفية وإصدارات ال pods على خوادم CocoaPods. يبقى الكود المصدري في مستودع Git الخاص بالمطور، بينما يخزن Trunk ملفات podspec والروابط فقط.
• إدارة الوصول — إمكانية إضافة وإزالة مالكي ال pods ونقل حقوق النشر ووضع علامة على ال pods كمهملة.

تم بناء بنية Trunk على مجموعة Ruby on Rails مع قاعدة بيانات PostgreSQL. تستخدم الخدمة API HTTP بتنسيق JSON لجميع العمليات، وعميل CLI pod trunk هو جزء من توزيعة CocoaPods ويتم تثبيته مع الحزمة الرئيسية cocoapods.

حتى الآن، تم نشر أكثر من 100,000 pod عبر Trunk، ويتجاوز إجمالي التنزيلات 50 مليار. يعالج الخادم آلاف الطلبات يومياً للنشر والتحديث من مطورين حول العالم.

التسجيل والمصادقة

قبل نشر pod، يجب عليك التسجيل في Trunk. تتكون العملية من خطوة واحدة — أمر pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, تطوير iOS'

بعد تنفيذ الأمر، يتم إرسال رابط تأكيد إلى البريد الإلكتروني المحدد. يؤدي النقر على الرابط إلى تفعيل الحساب وإنشاء رمز جلسة يتم تخزينه في سلسلة مفاتيح النظام (Keychain على macOS، gnome-keyring أو ما يعادله على Linux). يتم استخدام الرمز تلقائياً في جميع عمليات pod trunk اللاحقة.

المعامل --description اختياري لكن موصى به — يساعد في تحديد الجلسة عند عرض الجلسات النشطة عبر pod trunk me. إذا كنت تعمل من عدة أجهزة (محطة عمل، خادم CI)، سيسمح الوصف بتمييز جلسة عن أخرى.

للتحقق من حالة المصادقة، استخدم الأمر:

pod trunk me

يظهر الإخراج البريد الإلكتروني والاسم وقائمة ال pods الخاصة بك (إذا كنت قد نشرت من قبل) والجلسات النشطة. مثال على النتيجة:

  - Name: Your Name
  - Email: your@email.com
  - Since: 2024-03-15 10:30 UTC
  - Pods:
    - MyLibrary
    - AnotherPod
  - Sessions:
    - 2024-03-15 10:30 UTC - MacBook Pro, تطوير iOS

على خوادم CI (GitHub Actions، GitLab CI، Jenkins)، تتم المصادقة عبر رمز يتم تمريره من خلال متغير البيئة COCOAPODS_TRUNK_TOKEN. يمكن الحصول على الرمز بالأمر:

pod trunk me --token-only

يتم تخزين هذا الرمز في إعدادات CI كمتغير سري، ويستخدم في خطوة النشر دون حاجة لتسجيل متكرر. مثال لـ GitHub Actions:

env:
  COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

هام: الرمز يمنح وصولاً كاملاً لإدارة ال pods المرتبطة بالحساب. لا تنشره أبداً في المستودعات العامة أو تشاركه مع أطراف ثالثة. في حالة الاختراق، يمكن إبطال الرمز عبر pod trunk remove-session أو حذف جميع الجلسات من خلال لوحة التحكم على موقع CocoaPods.

إعداد podspec

ملف podspec (.podspec أو .podspec.json) هو بيان المكتبة الذي يحتوي على البيانات الوصفية والتبعيات ومعلومات المنصات والكود المصدري. يستخدم Trunk هذا الملف للتحقق من الصحة وتسجيل ال pod. يبدو podspec الأدنى للنشر كما يلي:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'وصف مختصر للمكتبة'
  s.description  = 'وصف مفصل مع شرح الإمكانيات'
  s.homepage     = 'https://github.com/username/MyLibrary'
  s.license      = { :type => 'MIT', :file => 'LICENSE' }
  s.author       = { 'Your Name' => 'your@email.com' }
  s.source       = { :git => 'https://github.com/username/MyLibrary.git', :tag => s.version.to_s }
  s.source_files = 'Sources/**/*.{swift,h,m}'
  s.platform     = :ios, '12.0'
  s.swift_version = '5.7'
end

الحقول الرئيسية في podspec:

• name — اسم ال pod، يجب أن يكون فريداً في سجل Trunk. يتم تسجيل الأسماء على أساس أسبقية الحجز — إذا كان الاسم محجوزاً، سيتم رفض النشر.
• version — إصدار دلالي بتنسيق MAJOR.MINOR.PATCH. لا يقبل Trunk إعادة نشر نفس الإصدار — يجب زيادة الرقم.
• source — رابط مستودع Git والعلامة. لا يخزن Trunk الكود المصدري، لذلك يجب أن يكون المستودع متاحاً للاستنساخ.
• platform — المنصة المستهدفة (iOS، macOS، tvOS، watchOS) والحد الأدنى لإصدار SDK.
• license — نوع الترخيص. يوصى بتحديد MIT أو Apache-2.0 أو BSD أو ترخيص مفتوح المصدر آخر.

قبل النشر، يجب التحقق من صحة podspec باستخدام المدقق:

pod lib lint MyLibrary.podspec

يتحقق المدقق من بناء الجملة والحقول الإلزامية وصحة مسارات الملفات وقابلية حل التبعيات. إذا تم استخدام مصادر خاصة أثناء الفحص، يتم إضافة العلم --sources. لتخطي تحميل الشبكة (فحص محلي فقط)، يستخدم العلم --local-only.

النشر عبر pod trunk push

الأمر الرئيسي لنشر pod هو pod trunk push. يرسل ملف podspec إلى خادم Trunk، حيث يخضع للتحقق الكامل ويتم تسجيله في السجل العام. الصيغة:

pod trunk push MyLibrary.podspec

العلم --allow-warnings يسمح بالنشر في حالة وجود تحذيرات. افتراضياً، أي تحذيرات تمنع النشر. إذا كانت المكتبة تحتوي على تحذيرات معروفة لا تؤثر على الوظيفة، يمكنك استخدام هذا العلم. هام: الأخطاء تمنع النشر دائماً بغض النظر عن الأعلام.

العلم --synchronous يجعل الطلب متزامناً — ينتظر الطرفية اكتمال التحقق على الخادم. افتراضياً، يعود الأمر بالتحكم فوراً بعد الإرسال، ويعالج الخادم النشر بشكل غير متزامن. الوضع المتزامن مفيد في CI/CD عندما تعتمد الخطوة التالية في pipeline على نجاح النشر.

العلم --skip-import-validation يتخطى التحقق من استيراد المكتبة في مشروع اختباري. هذا يسرع النشر ولكنه لا يضمن أن المكتبة تترجم فعلاً. استخدم هذا العلم فقط إذا كنت واثقاً من صحة البناء.

مثال على النشر بخيارات نموذجية:

pod trunk push MyLibrary.podspec \
  --allow-warnings \
  --synchronous \
  --skip-import-validation

بعد النشر الناجح، يعيد Trunk JSON بالتفاصيل:

  Congrats

  MyLibrary (0.1.0) successfully published

  Pod URL: https://cocoapods.org/pods/MyLibrary

تصبح المكتبة متاحة للتثبيت عبر Podfile في أي مشروع iOS أو macOS. عادةً، يتم تحديث فهرس بحث CocoaPods في غضون دقائق، لكن في حالات نادرة قد يستغرق الفهرسة ما يصل إلى ساعة.

قيود مهمة: إصدار pod المنشور لا يمكن حذفه. هذا لمنع تعطل المشاريع التي تستخدم هذا الإصدار بالفعل. إذا كان النشر خاطئاً، يمكنك نشر الإصدار التالي مع التصحيح، لكن الاسترجاع مستحيل. الاستثناء هو pod trunk delete، المتاح فقط لموظفي CocoaPods ويستخدم في الحالات القصوى (انتهاك الترخيص، كود ضار).

إدارة الإصدارات والوصول

يوفر CocoaPods Trunk عدة أوامر لإدارة ال pods المنشورة:

إضافة المالكين

لنقل حقوق نشر pod إلى مطور آخر، استخدم الأمر:

pod trunk add-owner MyLibrary developer@email.com

بعد التنفيذ، يحصل المالك الجديد على وصول كامل لإدارة ال pod: نشر إصدارات جديدة، إضافة وإزالة مالكين آخرين، وضع علامة على ال pod كمهمل. يمكن أن يكون المالك أي مستخدم مسجل في Trunk — التسجيل المسبق إلزامي.

إزالة المالكين

إذا غادر مطور المشروع أو لم يعد يجب أن يكون لديه حق الوصول إلى ال pod:

pod trunk remove-owner MyLibrary developer@email.com

يمكن فقط للمالك الحالي إزالة مالك. لا يمكن إزالة المالك الأخير لل pod — يجب أولاً إضافة مالك جديد. هذا يمنع أن يصبح ال pod بلا مالك ويصبح مهملاً.

وضع علامة على pod كمهمل

إذا لم تعد المكتبة مدعومة، يمكنك وضع علامة عليها كمهملة (deprecated). هذا لا يزيل ال pod من السجل، لكنه يضيف تحذيراً للمستخدمين عند التثبيت:

pod trunk deprecate MyLibrary

يمكنك اختيارياً تحديد pod بديل:

pod trunk deprecate MyLibrary --in-favor-of=NewLibrary

عند تثبيت pod مهمل، يعرض CocoaPods تحذيراً في الطرفية ويوصي بالتبديل إلى البديل المحدد. هذه هي الطريقة الصحيحة لإنهاء دعم مكتبة دون تعطيل بناء المشاريع الحالية.

عرض معلومات ال pod

معلومات ال pod متاحة عبر الأمر pod trunk info:

pod trunk info MyLibrary

يعرض الأمر جميع إصدارات ال pod وتواريخ النشر وقائمة المالكين والحالة (نشط/مهمل). لعرض تفاصيل إصدار معين، استخدم pod spec cat MyLibrary 0.1.0.

الأخطاء والحلول

عند العمل مع Trunk، غالباً ما يواجه المطورون أخطاء نموذجية. دعنا نستعرض الأكثر شيوعاً:

خطأ المصادقة

العرض: [!] Authentication failed. You need to register a session first.
السبب: رمز جلسة مفقود أو منتهي الصلاحية. الرموز لها فترة صلاحية محدودة (30 يوماً بدون نشاط افتراضياً).
الحل: أعد تنفيذ pod trunk register your@email.com 'Your Name'. إذا كنت تستخدم CI، تحقق من تحديث متغير البيئة COCOAPODS_TRUNK_TOKEN وقم بإنشاء رمز جديد إذا لزم الأمر.

تضارب الإصدارات

العرض: [!] You have already pushed version 0.1.0 for MyLibrary.
السبب: محاولة إعادة نشر إصدار موجود. لا يسمح Trunk بالكتابة فوق الإصدارات.
الحل: قم بزيادة الإصدار في podspec وفقاً للتحكم الدلالي بالإصدارات. إذا أخطأت في podspec، انشر الإصدار التالي مع التصحيح.

خطأ التحقق من podspec

العرض: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
السبب: مسار غير صحيح لملفات المصدر في حقل source_files.
الحل: تحقق من المسارات في podspec، نفذ pod lib lint محلياً حتى يتم حل جميع الأخطاء، ثم أعد النشر. استخدم أنماط glob: Classes/**/*.{h,m}، Sources/MyLibrary/**/*.swift.

انتهاء المهلة

العرض: [!] Connection to trunk.cocoapods.org failed. Timeout.
السبب: مشاكل في الشبكة أو عدم توفر خادم Trunk مؤقتاً.
الحل: تحقق من توفر الخادم: curl -I https://trunk.cocoapods.org. إذا كان الخادم يستجيب، أعد الأمر بعد بضع دقائق. قد يكون عنوان IP الخاص بك محظوراً — جرب من اتصال آخر أو عبر VPN.

عدم وجود وصول إلى ال pod

العرض: [!] You do not have permission to push to MyLibrary.
السبب: أنت لست مالك ال pod. يحدث هذا إذا كان شخص ما قد سجل pod بهذا الاسم بالفعل.
الحل: اتصل بالمالك الحالي لل pod (يمكن معرفته عبر pod trunk info MyLibrary) واطلب منه إضافتك عبر pod trunk add-owner. إذا كان اسم ال pod محجوزاً، فكر في اسم بديل.