chore(release): consolidate maintenance commands

- Add metadata update and Xcode scheme test wrapper scripts
- Add podspec lint mode to the dependency-aware publishing script
- Replace repeated lint, metadata, and Xcode command lists in release docs

Author: iziz

README.md

@@ -398,6 +398,15 @@ For user-reported numbering-plan gaps that are not yet in upstream metadata, fol
 
 ## Updating Metadata
 
+Use the all-in-one updater for normal metadata releases:
+
+```bash
+swift scripts/updateMetadata.swift <libphonenumber-version> --dry-run
+swift scripts/updateMetadata.swift <libphonenumber-version>
+```
+
+Use `--only main,geocoding` or `--skip carrier,timezones` when the release intentionally covers only specific metadata families. See the [release runbook](docs/RELEASE_RUNBOOK.md) for the full release flow.
+
 ### Main And Short-Number Metadata
 
 Run the metadata generator from the `scripts` directory:
@@ -444,19 +453,13 @@ git diff --check
 For Swift facade changes:
 
 ```bash
-pod lib lint libPhoneNumber-iOS-SwiftCore.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftGeocoding.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftShortNumber.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftUI.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-Swift.podspec --allow-warnings --include-podspecs='*.podspec'
+swift scripts/publishPodspecs.swift --lint
 ```
 
 For Xcode schemes:
 
 ```bash
-xcodebuild test -scheme libPhoneNumber -destination 'platform=iOS Simulator,name=iPhone 16'
-xcodebuild test -scheme libPhoneNumberGeocoding -destination 'platform=iOS Simulator,name=iPhone 16'
-xcodebuild test -scheme libPhoneNumberShortNumber -destination 'platform=iOS Simulator,name=iPhone 16'
+swift scripts/testXcodeSchemes.swift
 ```
 
 ## Release Checklist
@@ -470,7 +473,10 @@ xcodebuild test -scheme libPhoneNumberShortNumber -destination 'platform=iOS Sim
    swift scripts/updateProjectVersions.swift <new-version>
    ```
 3. Run the validation matrix.
-4. Lint the affected podspecs.
+4. Lint podspecs:
+   ```bash
+   swift scripts/publishPodspecs.swift --lint
+   ```
 5. Open a pull request with upstream version, parity results, and test results.
 6. Create a GitHub release after merge.
 7. Push updated podspecs in dependency order:

docs/RELEASE_RUNBOOK.md

@@ -35,31 +35,34 @@ If the release is for a user-reported numbering-plan issue, add or run a focused
 
 ## Update Metadata
 
-Update main, testing, and short-number metadata:
+Run the all-in-one metadata updater first. Use `--dry-run` to validate downloads, parsing, and generated outputs without changing checked-in metadata:
 
 ```bash
-swift scripts/metadataGenerator.swift <metadata-ref> --pretty
+swift scripts/updateMetadata.swift <metadata-ref> --dry-run
 ```
 
-Update geocoding metadata when upstream geocoding resources changed:
+Update all checked-in metadata families:
 
 ```bash
-swift scripts/updateGeocodingMetadata.swift <metadata-ref> --replace-bundle
+swift scripts/updateMetadata.swift <metadata-ref>
 ```
 
-Update carrier metadata when upstream carrier resources changed:
+Limit the update when only specific metadata families are in scope:
 
 ```bash
-swift scripts/updateCarrierMetadata.swift <metadata-ref> --replace-bundle
+swift scripts/updateMetadata.swift <metadata-ref> --only main,geocoding
+swift scripts/updateMetadata.swift <metadata-ref> --skip carrier,timezones
 ```
 
-Update timezone metadata when upstream timezone resources changed:
+The wrapper runs these underlying generators in order:
 
-```bash
-swift scripts/updateTimeZonesMetadata.swift <metadata-ref> --replace-bundle
-```
+- `scripts/metadataGenerator.swift` for main, testing, and short-number metadata.
+- `scripts/updateGeocodingMetadata.swift` for geocoding databases.
+- `scripts/updateCarrierMetadata.swift` for carrier metadata.
+- `scripts/updateTimeZonesMetadata.swift` for timezone metadata.
+- `scripts/checkMetadataFreshness.swift --current-ref <metadata-ref>` after checked-in updates.
 
-Use `--output <dir>` instead of `--replace-bundle` when reviewing generated artifacts before changing checked-in bundles.
+Use the individual generator scripts only when debugging or intentionally updating one metadata family outside the normal release flow.
 
 ## Version Bump
 
@@ -96,34 +99,20 @@ git diff --check
 Run the main Xcode schemes:
 
 ```bash
-xcodebuild test -scheme libPhoneNumber -destination 'platform=iOS Simulator,name=iPhone 16'
-xcodebuild test -scheme libPhoneNumberGeocoding -destination 'platform=iOS Simulator,name=iPhone 16'
-xcodebuild test -scheme libPhoneNumberShortNumber -destination 'platform=iOS Simulator,name=iPhone 16'
+swift scripts/testXcodeSchemes.swift
 ```
 
 If the simulator destination is ambiguous, use a concrete UDID:
 
 ```bash
 xcodebuild -scheme libPhoneNumber -showdestinations
-xcodebuild test -scheme libPhoneNumber -destination 'id=<simulator-udid>'
+swift scripts/testXcodeSchemes.swift --destination 'id=<simulator-udid>'
 ```
 
 Run CocoaPods lint for every shipped podspec when packaging, dependency, or release metadata changed:
 
 ```bash
-pod lib lint libPhoneNumber-iOS.podspec --allow-warnings
-pod lib lint libPhoneNumberGeocoding.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumberShortNumber.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumberCarrier.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumberTimeZones.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftCore.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftGeocoding.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftShortNumber.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftCarrier.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftTimeZones.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftUI.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-SwiftUIEnrichment.podspec --allow-warnings --include-podspecs='*.podspec'
-pod lib lint libPhoneNumber-iOS-Swift.podspec --allow-warnings --include-podspecs='*.podspec'
+swift scripts/publishPodspecs.swift --lint
 ```
 
 Re-run freshness after the metadata update to confirm the checked-in metadata matches the selected upstream ref:

docs/TESTING.md

@@ -64,24 +64,23 @@ See `docs/UPSTREAM_PARITY.md` for the full parity workflow.
 Run the three main schemes on an iOS Simulator:
 
 ```bash
-xcodebuild test -scheme libPhoneNumber -destination 'platform=iOS Simulator,name=iPhone 16'
-xcodebuild test -scheme libPhoneNumberGeocoding -destination 'platform=iOS Simulator,name=iPhone 16'
-xcodebuild test -scheme libPhoneNumberShortNumber -destination 'platform=iOS Simulator,name=iPhone 16'
+swift scripts/testXcodeSchemes.swift
 ```
 
 If the destination name is ambiguous or unavailable, list destinations and use a simulator UDID:
 
 ```bash
 xcodebuild -scheme libPhoneNumber -showdestinations
-xcodebuild test -scheme libPhoneNumber -destination 'id=<simulator-udid>'
+swift scripts/testXcodeSchemes.swift --destination 'id=<simulator-udid>'
 ```
 
 Using a fresh `-derivedDataPath` is useful when code coverage files or stale derived data create noisy warnings:
 
 ```bash
-xcodebuild test -scheme libPhoneNumberShortNumber \
-  -destination 'id=<simulator-udid>' \
-  -derivedDataPath /tmp/libphone-xc-shortnumber-dd
+swift scripts/testXcodeSchemes.swift \
+  --destination 'id=<simulator-udid>' \
+  --derived-data-root /tmp/libphone-xc-dd \
+  libPhoneNumberShortNumber
 ```
 
 ## Required Matrix By Change Type
@@ -98,7 +97,7 @@ For metadata updates:
 - `swift scripts/checkMetadataFreshness.swift --current-ref <metadata-ref> --output .build/metadata-freshness`
 - `swift scripts/checkUpstreamTestParity.swift --upstream-ref <metadata-ref>`
 - `swift scripts/checkUpstreamAPIParity.swift --upstream-ref <metadata-ref>`
-- `swift scripts/updateGeocodingMetadata.swift <metadata-ref> --output /tmp/geocoding-review` if geocoding metadata changed upstream.
+- `swift scripts/updateMetadata.swift <metadata-ref> --dry-run`
 - `scripts/testGeocodingMetadataUpdater.sh` if the geocoding updater changed.
 - Update `docs/METADATA_UPDATE_LOG.md` with the upstream comparison and validation results.
 - `swift test`
@@ -121,47 +120,28 @@ For geocoding behavior changes:
 
 - `swift test`
 - `LC_ALL=ko_KR.UTF-8 LANG=ko_KR.UTF-8 swift test`
-- `xcodebuild test -scheme libPhoneNumberGeocoding -destination 'id=<simulator-udid>'`
+- `swift scripts/testXcodeSchemes.swift --destination 'id=<simulator-udid>' libPhoneNumberGeocoding`
 - `git diff --check`
 
 For short-number behavior changes:
 
 - `swift test`
-- `xcodebuild test -scheme libPhoneNumberShortNumber -destination 'id=<simulator-udid>'`
+- `swift scripts/testXcodeSchemes.swift --destination 'id=<simulator-udid>' libPhoneNumberShortNumber`
 - `git diff --check`
 
 For Swift facade changes:
 
 - `swift test`
 - `LC_ALL=ko_KR.UTF-8 LANG=ko_KR.UTF-8 swift test`
 - `swift build -c release`
-- `pod lib lint libPhoneNumber-iOS-SwiftCore.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftGeocoding.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftShortNumber.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftCarrier.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftTimeZones.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftUI.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftUIEnrichment.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-Swift.podspec --allow-warnings --include-podspecs='*.podspec'`
+- `swift scripts/publishPodspecs.swift --lint`
 - Confirm the facade remains a thin wrapper over the Objective-C core instead of duplicating phone-number logic.
 - See `docs/SWIFT_FACADE_MODULE_SPLIT.md` before changing module boundaries.
 
 For packaging changes:
 
 - `swift scripts/checkVersionConsistency.swift`
-- `pod lib lint libPhoneNumber-iOS.podspec --allow-warnings`
-- `pod lib lint libPhoneNumberGeocoding.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumberShortNumber.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumberCarrier.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumberTimeZones.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftCore.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftGeocoding.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftShortNumber.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftCarrier.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftTimeZones.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftUI.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-SwiftUIEnrichment.podspec --allow-warnings --include-podspecs='*.podspec'`
-- `pod lib lint libPhoneNumber-iOS-Swift.podspec --allow-warnings --include-podspecs='*.podspec'`
+- `swift scripts/publishPodspecs.swift --lint`
 
 ## Locale-Sensitive Tests
 

scripts/publishPodspecs.swift

@@ -4,6 +4,7 @@ import Foundation
 
 struct Options {
   var shouldPublish = false
+  var shouldLint = false
   var skipExisting = true
   var retries = 2
   var waitTimeout = 120
@@ -48,13 +49,14 @@ func usage() -> String {
     swift scripts/publishPodspecs.swift [options] [podspec ...]
 
   Options:
+    --lint                Lint podspecs in dependency order without publishing.
     --publish             Push missing podspec versions to CocoaPods trunk.
     --no-skip-existing    Attempt to push versions even when trunk already has them.
     --retries <count>     Retry failed trunk pushes. Default: 2.
     --wait-timeout <sec>  Wait for trunk visibility after each push. Default: 120.
     --help                Print this help.
 
-  Without --publish, the script only prints dependency order and trunk status.
+  Without --lint or --publish, the script only prints dependency order and trunk status.
   """
 }
 
@@ -66,6 +68,8 @@ func parseOptions(_ arguments: [String]) throws -> Options {
     let argument = arguments[index]
 
     switch argument {
+    case "--lint":
+      options.shouldLint = true
     case "--publish":
       options.shouldPublish = true
     case "--no-skip-existing":
@@ -240,7 +244,7 @@ func waitForTrunkVersion(name: String, version: String, timeout: Int) throws ->
 }
 
 func printPlan(_ podspecs: [Podspec]) {
-  print("Dependency-aware CocoaPods trunk order:")
+  print("Dependency-aware CocoaPods podspec order:")
   for (index, podspec) in podspecs.enumerated() {
     let localDependencies = podspec.dependencies.filter { dependencyName in
       podspecs.contains { $0.name == dependencyName }
@@ -253,6 +257,28 @@ func printPlan(_ podspecs: [Podspec]) {
   }
 }
 
+func lint(_ podspec: Podspec) throws -> Bool {
+  print("[lint] \(podspec.path)")
+  let exitCode = try runStreaming(
+    "pod",
+    [
+      "lib",
+      "lint",
+      podspec.path,
+      "--allow-warnings",
+      "--include-podspecs=*.podspec",
+    ]
+  )
+
+  if exitCode == 0 {
+    print("[ok] \(podspec.name) \(podspec.version) passed lint")
+    return true
+  }
+
+  print("[warn] \(podspec.name) \(podspec.version) lint failed with exit code \(exitCode)")
+  return false
+}
+
 func publish(_ podspec: Podspec, options: Options) throws -> Bool {
   let isPublished = try trunkHasVersion(name: podspec.name, version: podspec.version)
 
@@ -318,6 +344,28 @@ do {
 
   printPlan(orderedPodspecs)
 
+  if options.shouldLint {
+    var failedLintPodspecs: [String] = []
+    for podspec in orderedPodspecs {
+      if !(try lint(podspec)) {
+        failedLintPodspecs.append("\(podspec.name) \(podspec.version)")
+      }
+    }
+
+    if !failedLintPodspecs.isEmpty {
+      print("Failed podspec lint validations:")
+      for failedPodspec in failedLintPodspecs {
+        print("- \(failedPodspec)")
+      }
+      exit(1)
+    }
+
+    print("All podspecs passed lint.")
+    if !options.shouldPublish {
+      exit(0)
+    }
+  }
+
   var failedPodspecs: [String] = []
   for podspec in orderedPodspecs {
     if !(try publish(podspec, options: options)) {