Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
178 lines (115 loc) · 8.94 KB

CONTRIBUTING.md

File metadata and controls

178 lines (115 loc) · 8.94 KB

Contributing

The following is a set of guidelines for contributing to this project. Please take a moment to read through them before submitting your first PR.

This is a monorepo containing the iOS/Swift, Android, and (forthcoming) React Native implementations of the Shopify Checkout Kit. Each platform has its own conventions, tooling, and release process; the shared guidelines below apply to all of them.

Code of Conduct

This project and everyone participating in it are governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@shopify.com.

Welcomed contributions

  • Reporting issues with existing features
  • Bug fixes
  • Performance improvements
  • Documentation
  • Usability improvements

Things we won't merge

  • Additional dependencies that limit SDK use (e.g. unnecessary Swift or Android dependencies)
  • Any changes that break existing tests
  • Any changes without sufficient tests

Proposing features

When in doubt about whether we will be interested in including a new feature, please open an issue to propose the feature so we can confirm scope before it is implemented.

NOTE: Issues that have not been active for 30 days will be marked as stale, and subsequently closed after a further 7 days of inactivity.

How to contribute (general flow)

  1. Fork the repo and branch off of main.
  2. Create a feature branch in your fork.
  3. Make changes and add any relevant tests.
  4. Run the platform-specific formatter / linter (see below).
  5. Verify the changes locally (e.g. via the platform's sample app).
  6. Commit your changes and push.
  7. Ensure all checks (tests, lint) are passing in GitHub.
  8. Open a pull request with a detailed description of what is changing and why.

Swift (platforms/swift/)

Prerequisites

This project uses Mint to manage Swift linting tools (SwiftLint and SwiftFormat) at pinned versions via platforms/swift/Mintfile. This ensures consistent formatting across all contributors and CI.

Shopify employees (from the repo root):

dev up

External contributors:

brew install mint
cd platforms/swift && mint bootstrap

Formatting

cd platforms/swift && ./Scripts/lint fix

Public API surface

The library's public API is tracked via committed baselines under platforms/swift/api/, one JSON file per module (ShopifyCheckoutProtocol.json, ShopifyCheckoutKit.json, ShopifyAcceleratedCheckouts.json). They are produced by xcrun swift-api-digester -dump-sdk against the built .swiftmodule files. The unified Breaking Changes CI workflow runs dev swift api check on every PR that touches Swift sources and fails if the digester output for any module diverges from its committed baseline.

If your change intentionally modifies the public API:

  1. Run dev swift api dump from the repo root to regenerate the baselines.
  2. Review the diff in platforms/swift/api/*.json alongside your code changes.
  3. Commit the updated JSON files in the same PR.

When dev swift api check fails, it prints both the unified diff and a swift-api-digester -diagnose-sdk summary categorizing the changes (removed, renamed, type/protocol/inheritance changes). Use the diagnose summary to decide whether the diff is intentional.

Releasing a new Swift version

Open a pull request with the following changes:

  1. Bump the package version in platforms/swift/Sources/ShopifyCheckoutKit/ShopifyCheckoutKit.swift.
  2. Bump the metadata version in platforms/swift/Sources/ShopifyCheckoutKit/MetaData.swift.
  3. Bump the podspec version in ShopifyCheckoutKit.podspec (at the repo root).
  4. Add an entry to the top of platforms/swift/CHANGELOG.md.
  5. If the React Native package should consume this Swift SDK release, update checkoutKit.nativeSdkVersions.ios in platforms/react-native/modules/@shopify/checkout-kit-react-native/package.json to the same version.

All Swift version declarations must match exactly. Supported release versions are X.Y.Z and prerelease versions are X.Y.Z-{alpha|beta|rc}.N.

Once merged, run the Release package workflow:

  1. Select iOS as the platform.
  2. Enter the expected version. The workflow reads the SDK version from the checked-in files and fails if the typed version does not match.
  3. Leave dry-run enabled first to review the release plan.
  4. Rerun with dry-run disabled. By default this creates a draft GitHub Release with the bare semver tag (e.g. 3.8.1) for human review.
  5. Publish the draft release when ready. Publishing the draft kicks off the Swift publish workflow, which publishes the new version to CocoaPods.

Android (platforms/android/)

Formatting

This project uses detekt for Kotlin linting and formatting. From platforms/android/:

./gradlew detekt --auto-correct

To check for lint issues without auto-correcting:

./gradlew detekt

Public API surface

The library's public API is tracked via a committed baseline at platforms/android/lib/api/lib.api, managed by the binary-compatibility-validator Gradle plugin. The unified Breaking Changes CI workflow runs ./gradlew :lib:apiCheck on every PR that touches Android sources and fails if the compiled public API diverges from the baseline.

If your change intentionally modifies the public API:

  1. Run dev android api dump from the repo root (or ./gradlew :lib:apiDump from platforms/android/) to regenerate the baseline.
  2. Review the diff in platforms/android/lib/api/lib.api alongside your code changes.
  3. Commit the updated .api file in the same PR.

If you did not intend to change public API and apiCheck is failing, the diff shows what your change inadvertently affected — treat it as a signal that something in your PR has consumer-visible impact.

Releasing a new Android version

Open a pull request with the following changes:

  1. Bump the versionName in platforms/android/lib/build.gradle.
  2. Add an entry to the top of platforms/android/CHANGELOG.md.
  3. If the React Native package should consume this Android SDK release, update checkoutKit.nativeSdkVersions.android in platforms/react-native/modules/@shopify/checkout-kit-react-native/package.json to the same version.

Supported release versions are X.Y.Z and prerelease versions are X.Y.Z-{alpha|beta|rc}.N.

Once merged, run the Release package workflow:

  1. Select Android as the platform.
  2. Enter the expected version. The workflow reads the SDK version from platforms/android/lib/build.gradle and fails if the typed version does not match.
  3. Leave dry-run enabled first to review the release plan.
  4. Rerun with dry-run disabled. By default this creates a draft GitHub Release with the android/-prefixed tag (e.g. android/3.0.1) for human review.
  5. Publish the draft release when ready. Publishing the draft kicks off the Android publish workflow. A manual approval by a maintainer is required before publication to Maven Central.

React Native (platforms/react-native/)

Native SDK dependency versions

The React Native package reads its published native SDK dependency versions from platforms/react-native/modules/@shopify/checkout-kit-react-native/package.json:

"checkoutKit": {
  "nativeSdkVersions": {
    "ios": "4.0.0-alpha.1",
    "android": "4.0.0-alpha.1"
  }
}

When updating the Swift or Android SDK version that React Native should consume, update the matching checkoutKit.nativeSdkVersions entry in this package file. These values drive RNShopifyCheckoutKit.podspec for iOS and the module/sample Gradle dependencies for Android, so they must stay aligned with the published native SDK versions used by the React Native release.

Public API surface

The library's public API is tracked via a committed report at platforms/react-native/modules/@shopify/checkout-kit-react-native/api/checkout-kit-react-native.api.md, generated by @microsoft/api-extractor from the bob-produced .d.ts files. The unified Breaking Changes CI workflow runs dev rn api check on every PR that touches React Native sources and fails if the regenerated report diverges from the committed one.

If your change intentionally modifies the public API:

  1. Run dev rn api dump from the repo root to regenerate the report.
  2. Review the diff in platforms/react-native/modules/@shopify/checkout-kit-react-native/api/checkout-kit-react-native.api.md alongside your code changes.
  3. Commit the updated .api.md file in the same PR.

If you did not intend to change public API and api:check is failing, the diff shows what your change inadvertently affected — treat it as a signal that something in your PR has consumer-visible impact.