CocoaPods Trunk: ano ito, pag-publish ng mga library sa pamamagitan ng Trunk

Ano ang CocoaPods Trunk?

CocoaPods Trunk — ay isang server infrastructure na inilunsad noong 2015 para sa sentralisadong pag-publish ng mga pod library. Bago dumating ang Trunk, ang bawat pod ay ipinamamahagi sa pamamagitan ng Git repository: ang developer ay kailangang lumikha ng pampublikong repository, magdagdag ng podspec file, at magpadala ng Pull Request sa sentral na repository na CocoaPods/Specs. Ang ganitong approach ay nangangailangan ng manual na moderasyon at nagdulot ng mga pagkaantala sa pag-publish ng mga update.

Nalutas ng Trunk ang mga problemang ito sa pamamagitan ng pagbibigay ng pinag-isang API para sa pag-publish, pag-update, at pagtanggal ng mga pod. Ang serbisyo ay may apat na pangunahing bahagi:

• Pagpapatotoo — pagrehistro na may kumpirmasyon sa email at pamamahala ng mga token ng session. Bawat developer ay tumatanggap ng natatanging token na nakatali sa kanyang account at mga device.
• Validation — awtomatikong pagsusuri ng podspec bago ang pag-publish, kabilang ang syntactic analysis, linting ng mga dependency, at pagsusuri ng compatibility ng platform.
• Pagho-host — pag-iimbak ng metadata at mga bersyon ng pod sa mga server ng CocoaPods. Ang source code ay nananatili sa Git repository ng developer, habang ang Trunk ay nag-iimbak lamang ng mga podspec file at link.
• Pamamahala ng access — kakayahang magdagdag at magtanggal ng mga may-ari ng pod, maglipat ng mga karapatan sa pag-publish, magmarka ng mga pod bilang luma na.

Ang arkitektura ng Trunk ay binuo sa Ruby on Rails stack na may PostgreSQL database. Gumagamit ang serbisyo ng HTTP API na may JSON format para sa lahat ng operasyon, at ang CLI client na pod trunk ay bahagi ng CocoaPods distribution at naka-install kasama ng pangunahing gem na cocoapods.

Sa kasalukuyan, mahigit 100,000 pod ang na-publish sa pamamagitan ng Trunk, na may kabuuang bilang ng mga download na lampas 50 bilyon. Araw-araw, pinoproseso ng serbisyo ang libu-libong kahilingan sa pag-publish at pag-update ng mga library mula sa mga developer sa buong mundo.

Pagrehistro at pagpapatotoo

Bago mag-publish ng pod, kailangan mong magrehistro sa Trunk. Ang proseso ay binubuo ng isang hakbang — ang utos na pod trunk register:

pod trunk register your@email.com 'Your Name' --description='MacBook Pro, pag-develop ng iOS'

Pagkatapos isagawa ang utos, isang email na may link ng kumpirmasyon ay ipinapadala sa tinukoy na address. Ang pag-click sa link ay mag-a-activate ng account at gagawa ng session token na naka-save sa system keychain (Keychain sa macOS, gnome-keyring o katumbas sa Linux). Ang token ay awtomatikong ginagamit sa lahat ng susunod na operasyon ng pod trunk.

Ang parameter na --description ay opsyonal ngunit inirerekomenda — tumutulong ito na makilala ang session kapag tinitingnan ang mga aktibong session sa pamamagitan ng pod trunk me. Kung nagtatrabaho ka sa maraming machine (workstation, CI server), ang paglalarawan ay magbibigay-daan sa iyo na makilala ang isang session mula sa iba.

Upang suriin ang status ng pagpapatotoo, gamitin ang sumusunod na utos:

pod trunk me

Ang output ay nagpapakita ng email, pangalan, listahan ng iyong mga pod (kung nag-publish ka na) at mga aktibong session. Halimbawang resulta:

  - 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, pag-develop ng iOS

Sa mga CI server (GitHub Actions, GitLab CI, Jenkins), ang pagpapatotoo ay ginagawa sa pamamagitan ng token na naipasa sa pamamagitan ng environment variable na COCOAPODS_TRUNK_TOKEN. Ang token ay maaaring makuha sa pamamagitan ng utos:

pod trunk me --token-only

Ang token na ito ay naka-save sa mga setting ng CI bilang secret variable, at sa yugto ng pag-publish ay ginagamit nang walang muling pagrehistro. Halimbawa para sa GitHub Actions:

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

Mahalaga: ang token ay nagbibigay ng buong access sa pamamahala ng mga pod na nakatali sa account. Huwag kailanman i-publish ito sa mga pampublikong repository o ibigay sa mga third party. Kung nakompromiso ang token, maaari itong bawiin sa pamamagitan ng pod trunk remove-session o tanggalin ang lahat ng session sa pamamagitan ng control panel sa website ng CocoaPods.

Paghahanda ng podspec

Ang podspec file (.podspec o .podspec.json) — ay ang manifest ng library na naglalaman ng metadata, mga dependency, impormasyon tungkol sa mga platform at source code. Ginagamit ng Trunk ang file na ito para sa validation at pagrehistro ng pod. Ang minimal na podspec para sa pag-publish ay ganito ang itsura:

Pod::Spec.new do |s|
  s.name         = 'MyLibrary'
  s.version      = '0.1.0'
  s.summary      = 'Maikling paglalarawan ng library'
  s.description  = 'Detalyadong paglalarawan na may paliwanag ng mga kakayahan'
  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

Mga pangunahing field ng podspec:

• name — pangalan ng pod, dapat ay natatangi sa Trunk registry. Ang mga pangalan ay nirerehistro batay sa prinsipyong 'unang dumating, unang nakuha' — kung ang pangalan ay ginagamit na, tatanggihan ang pag-publish.
• version — semantic version sa format na MAJOR.MINOR.PATCH. Hindi tinatanggap ng Trunk ang muling pag-publish ng parehong bersyon — kailangan mong taasan ang numero.
• source — link sa Git repository at tag. Hindi nag-iimbak ng source code ang Trunk, kaya ang repository ay dapat na ma-access para sa pag-clone.
• platform — target na platform (iOS, macOS, tvOS, watchOS) at minimum na bersyon ng SDK.
• license — uri ng lisensya. Inirerekomenda na tukuyin ang MIT, Apache-2.0, BSD o iba pang open source na lisensya.

Bago ang pag-publish, ang podspec ay dapat suriin para sa kawastuhan gamit ang linter:

pod lib lint MyLibrary.podspec

Sinusuri ng linter ang syntax, pagkakaroon ng mga mandatoryong field, kawastuhan ng mga path ng file, at resolvability ng mga dependency. Kung sa proseso ng linting ay gumagamit ng mga pribadong source (private specs), idinadagdag ang flag na --sources. Upang laktawan ang pag-download sa network (local check lang), ginagamit ang flag na --local-only.

Pag-publish sa pamamagitan ng pod trunk push

Ang pangunahing utos para sa pag-publish ng pod — pod trunk push. Ipinapadala nito ang podspec file sa Trunk server, kung saan sumasailalim ito sa buong validation at nirerehistro sa pampublikong rehistro. Syntax:

pod trunk push MyLibrary.podspec

Ang flag na --allow-warnings ay nagpapahintulot sa pag-publish kung may mga babala. Bilang default, anumang mga babala (warnings) ay humaharang sa pag-publish. Kung ang library ay may kilalang mga babala na hindi nakakaapekto sa functionality, maaari mong gamitin ang flag na ito. Mahalaga: ang mga error ay palaging humaharang sa pag-publish, anuman ang mga flag.

Ang flag na --synchronous ay ginagawang synchronous ang kahilingan — naghihintay ang terminal ng pagkumpleto ng validation sa server. Bilang default, ang utos ay nagbabalik ng control kaagad pagkatapos ng pagpapadala, at pinoproseso ng server ang pag-publish nang asynchronous. Ang synchronous mode ay kapaki-pakinabang sa CI/CD kapag ang susunod na hakbang ng pipeline ay nakadepende sa tagumpay ng pag-publish.

Ang flag na --skip-import-validation ay lumalaktaw sa pagsusuri ng import ng library sa isang test project. Pinapabilis nito ang pag-publish, ngunit hindi ginagarantiyahan na ang library ay talagang nagko-compile. Gamitin ang flag na ito lamang kung sigurado ka sa kawastuhan ng build.

Halimbawa ng pag-publish na may karaniwang mga opsyon:

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

Pagkatapos ng matagumpay na pag-publish, ang Trunk ay nagbabalik ng JSON na may mga detalye:

  Congrats

  MyLibrary (0.1.0) successfully published

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

Ang library ay nagiging available para sa pag-install sa pamamagitan ng Podfile ng anumang iOS o macOS project. Karaniwan, ang data sa CocoaPods search index ay ina-update sa loob ng ilang minuto, ngunit sa mga bihirang kaso, ang pag-index ay maaaring tumagal ng hanggang isang oras.

Mahalagang limitasyon: ang bersyon ng pod na na-publish na ay hindi maaaring tanggalin. Ito ay upang maiwasan ang pagkasira ng mga project na gumagamit na ng bersyong ito. Kung ang pag-publish ay nagtapos sa error, maaari mong i-publish ang susunod na bersyon na may pagwawasto, ngunit ang pagbabalik ay imposible. Exception — pod trunk delete, available lamang sa mga empleyado ng CocoaPods at inilalapat sa matinding kaso (paglabag sa lisensya, malisyosong code).

Pamamahala ng mga release at access

Ang CocoaPods Trunk ay nagbibigay ng ilang utos para sa pangangasiwa ng mga nai-publish na pod:

Pagdaragdag ng mga may-ari

Upang ilipat ang mga karapatan sa pag-publish ng pod sa ibang developer, gamitin ang sumusunod na utos:

pod trunk add-owner MyLibrary developer@email.com

Pagkatapos isagawa, ang bagong may-ari ay makakakuha ng buong access sa pamamahala ng pod: pag-publish ng mga bagong bersyon, pagdaragdag at pagtanggal ng ibang mga may-ari, pagmarka ng pod bilang luma na. Ang may-ari ay maaaring sinumang rehistradong user ng Trunk — kinakailangan ang paunang pagrehistro.

Pagtatanggal ng mga may-ari

Kung ang isang developer ay umalis sa project o hindi na dapat magkaroon ng access sa pod:

pod trunk remove-owner MyLibrary developer@email.com

Ang isang may-ari ay maaari lamang tanggalin ng kasalukuyang may-ari. Hindi maaaring tanggalin ang huling may-ari ng pod — kailangan munang magdagdag ng bago. Ito ay pumipigil sa sitwasyon kung saan ang pod ay naiwan na walang may-ari.

Pagmarka ng pod bilang luma na

Kung ang library ay hindi na suportado, maaari itong mamarkahan bilang luma na (deprecated). Hindi nito tinatanggal ang pod mula sa rehistro, ngunit nagdaragdag ng babala sa mga user kapag nag-i-install:

pod trunk deprecate MyLibrary

Opsyonal, maaaring tukuyin ang kapalit na pod:

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

Kapag nag-i-install ng lumang pod, ang CocoaPods ay nagpapakita ng babala sa terminal at nagrerekomenda na lumipat sa tinukoy na kapalit. Ito ang tamang paraan upang tapusin ang suporta ng isang library nang hindi sinisira ang build ng mga umiiral nang project.

Pagtingin ng impormasyon tungkol sa pod

Ang impormasyon tungkol sa pod ay available sa pamamagitan ng utos na pod trunk info:

pod trunk info MyLibrary

Ipinapakita ng utos ang lahat ng bersyon ng pod, mga petsa ng pag-publish, listahan ng mga may-ari, at status (aktibo/luma na). Upang tingnan ang mga detalye ng isang partikular na bersyon, gamitin ang pod spec cat MyLibrary 0.1.0.

Mga error at solusyon

Sa pagtatrabaho sa Trunk, ang mga developer ay madalas na nakakaranas ng mga karaniwang error. Tingnan natin ang mga pinakamadalas:

Error sa pagpapatotoo

Sintomas: [!] Authentication failed. You need to register a session first.
Sanhi: Nawawala o nag-expire na ang session token. Ang mga token ay may limitadong panahon ng bisa (default 30 araw na walang aktibidad).
Solusyon: Isagawa muli ang pod trunk register your@email.com 'Your Name'. Kung gumagamit ka ng CI, suriin ang pagiging bago ng variable na COCOAPODS_TRUNK_TOKEN at gumawa ng bagong token kung kinakailangan.

Salungatan ng bersyon

Sintomas: [!] You have already pushed version 0.1.0 for MyLibrary.
Sanhi: Pagtatangkang muling i-publish ang isang umiiral nang bersyon. Hindi pinapayagan ng Trunk ang pag-overwrite ng mga bersyon.
Solusyon: Taasan ang bersyon sa podspec ayon sa semantic versioning. Kung nagkamali ka sa podspec, i-publish ang susunod na bersyon na may pagwawasto.

Error sa validation ng podspec

Sintomas: [!] The spec did not pass validation. ERROR | [iOS] file patterns: Source files did not match any file.
Sanhi: Maling tinukoy ang path sa source file sa field na source_files.
Solusyon: Suriin ang mga path sa podspec, isagawa ang pod lib lint nang lokal hanggang maayos ang lahat ng error, pagkatapos ay ulitin ang pag-publish. Gumamit ng mga glob pattern: Classes/**/*.{h,m}, Sources/MyLibrary/**/*.swift.

Timeout ng koneksyon

Sintomas: [!] Connection to trunk.cocoapods.org failed. Timeout.
Sanhi: Mga problema sa network o pansamantalang hindi available ang Trunk server.
Solusyon: Suriin ang availability ng server: curl -I https://trunk.cocoapods.org. Kung ang server ay tumugon, ulitin ang utos pagkalipas ng ilang minuto. Maaaring naka-block ang iyong IP — subukan mula sa ibang koneksyon o sa pamamagitan ng VPN.

Walang access sa pod

Sintomas: [!] You do not have permission to push to MyLibrary.
Sanhi: Hindi ikaw ang may-ari ng pod. Ito ay nangyayari kung may nagrehistro na ng pod na may ganyang pangalan.
Solusyon: Makipag-ugnayan sa kasalukuyang may-ari ng pod (maaaring malaman sa pamamagitan ng pod trunk info MyLibrary) at hilingin na idagdag ka sa pamamagitan ng pod trunk add-owner. Kung ang pangalan ng pod ay ginagamit na, isaalang-alang ang alternatibong pangalan.