Skip to content

publishing.md

Latest commit

 

History

History
146 lines (111 loc) · 5.6 KB

publishing.md

File metadata and controls

146 lines (111 loc) · 5.6 KB
Raw

Publishing

  1. Set VERSION to the exact SemVer release version and create a release branch from an up-to-date master.
VERSION="<release-version>"
git fetch origin --tags
git switch master
git pull --ff-only origin master
git tag --list "$VERSION"
git switch -c "release-$VERSION"

VERSION keeps the branch name, tag, podspec checks, and PR title aligned across the release commands. It does not need to be exported because the commands read it through shell expansion; set it again if you continue the release from a new shell. git tag --list "$VERSION" should print nothing. Use bare version tags such as 0.2.0, not v0.2.0, because the podspec source tag is s.version.to_s.

  1. Update release metadata and docs.
  • Set s.version in oms-wallet-swift-sdk.podspec to $VERSION.
  • Keep the podspec s.readme URL versioned with s.version so CocoaPods renders the README for the published release.
  • Update the CocoaPods install snippet in README.md to the same version.
  • Update the exact-version Swift Package Manager text (the literal text "version" followed by the backticked version) in README.md to the same version. This is mandatory: scripts/verify.sh fails without it.
  • Update the Package.swift example in README.md (.upToNextMinor(from: "...")) to the same version. scripts/verify.sh also fails without it.
  • If public APIs, behavior, setup, or examples changed, update API.md and the relevant README sections in the same PR.
  • If the release contains breaking changes, update MIGRATION.md with steps from the previous published version.
  1. Validate the release branch.

Release verification requires Python 3.9 or later for the API generator.

scripts/verify.sh

This is the same command CI runs. It checks release version alignment, builds and tests the Swift package, checks the public API baseline, lints the local podspec, and builds both example apps for the iOS Simulator with normal automatic simulator signing.

  1. Push the branch and open the PR.
git diff --check
git status --short
git push -u origin "release-$VERSION"
gh pr create \
  --base master \
  --head "release-$VERSION" \
  --title "chore(release): $VERSION" \
  --template .github/PULL_REQUEST_TEMPLATE.md
  1. After merge, prepare master and confirm the public source URL is reachable.
VERSION="<release-version>"
git switch master
git pull --ff-only origin master
grep "s.version = \"$VERSION\"" oms-wallet-swift-sdk.podspec
GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote --exit-code https://github.com/0xsequence/swift-sdk.git HEAD

CocoaPods validates the podspec by cloning s.source, so the GitHub repo must be public before pod trunk push.

  1. Create the release tag, push it, and verify the pushed tag.
git tag -s "$VERSION" -m "$VERSION"
git push origin "$VERSION"
GIT_TERMINAL_PROMPT=0 git -c credential.helper= ls-remote --exit-code https://github.com/0xsequence/swift-sdk.git "refs/tags/$VERSION"
git fetch origin tag "$VERSION"
git show "$VERSION":oms-wallet-swift-sdk.podspec | grep "s.version = \"$VERSION\""

Existing release tags are annotated and signed. If signing is unavailable, stop and confirm the release policy before pushing an unsigned tag. Swift Package Manager resolves this pushed tag.

  1. Set up CocoaPods trunk auth and check pod ownership.
pod trunk me

If there is no active trunk session, register, confirm the CocoaPods email, then verify:

pod trunk register your@email.com "0xSequence" --description="MacBook"
pod trunk me

Check ownership:

pod trunk info oms-wallet-swift-sdk

For the first release, CocoaPods may report that no pod exists yet. If the pod exists, the publishing account from pod trunk me must be one of the owners.

  1. Validate and publish the CocoaPods spec from the same merged commit.
pod spec lint oms-wallet-swift-sdk.podspec --swift-version=6.0 --platforms=ios,macos
pod trunk push oms-wallet-swift-sdk.podspec --swift-version=6.0
pod trunk info oms-wallet-swift-sdk

Do not run pod trunk push until the matching git tag has been pushed. CocoaPods versions cannot be overwritten after publishing; if a bad podspec is published, release a new version instead.

If CocoaPods emits only reviewed warnings for a release, append --allow-warnings to both pod spec lint and pod trunk push. Do not use it to ignore unexplained warnings.

Alpha, Beta, and Snapshot Releases

Alpha and beta releases use the same release flow as stable releases. Set VERSION to a bare SemVer prerelease such as 0.2.1-alpha.1 or 0.2.1-beta.1, update s.version, update any exact install snippets that should point at the prerelease, validate, tag, and publish. Do not reuse a published prerelease version; CocoaPods and git tags are immutable.

Swift Package Manager resolves prereleases from the pushed git tag. CocoaPods publishes prerelease pod versions through pod trunk push the same way it publishes stable versions.

For snapshot testing, prefer branch or commit references instead of publishing a mutable package version:

.package(url: "https://github.com/0xsequence/swift-sdk.git", branch: "branch-name")
.package(url: "https://github.com/0xsequence/swift-sdk.git", revision: "<commit-sha>")
pod 'oms-wallet-swift-sdk',
    :git => 'https://github.com/0xsequence/swift-sdk.git',
    :commit => '<commit-sha>'

If a published snapshot artifact is explicitly required, use an immutable SemVer prerelease such as 0.2.1-snapshot.20260703.1 and follow the normal release flow. Treat it as permanent once pushed; do not expect CocoaPods or git tags to behave like mutable Maven -SNAPSHOT artifacts.