Update Publishing Docs and Actions

.github/workflows/publish.yml

@@ -17,15 +17,47 @@ jobs:
       - name: Setup
         uses: ./.github/actions/setup
 
+      - name: Validate versions match
+        id: validate-versions
+        run: |
+          # Extract version from package.json
+          PACKAGE_VERSION=$(node -p "require('./modules/@shopify/checkout-sheet-kit/package.json').version")
+
+          # Extract Git tag from release
+          GIT_TAG="${{ github.event.release.tag_name }}"
+
+          echo "📦 package.json version: $PACKAGE_VERSION"
+          echo "🏷️  Git tag: $GIT_TAG"
+
+          # Compare versions
+          if [ "$PACKAGE_VERSION" != "$GIT_TAG" ]; then
+            echo ""
+            echo "❌ ERROR: Version mismatch detected!"
+            echo ""
+            echo "The version in package.json ($PACKAGE_VERSION) does not match the Git tag ($GIT_TAG)."
+            echo ""
+            echo "Please ensure the following are updated before creating a release:"
+            echo "  1. modules/@shopify/checkout-sheet-kit/package.json"
+            echo "  2. Git tag should match package.json version exactly"
+            echo ""
+            echo "For pre-releases, use format: X.Y.Z-beta.N or X.Y.Z-rc.N"
+            echo ""
+            exit 1
+          fi
+
+          echo ""
+          echo "✅ All versions match! Proceeding with release..."
+          echo ""
+
       - name: Determine NPM tag
         id: npm-tag
         run: |
           # Read the version from package.json
           VERSION=$(node -p "require('./modules/@shopify/checkout-sheet-kit/package.json').version")
 
-          # Check if it's a "beta" or "rc" version
-          if [[ "$VERSION" == *"-beta"* ]] || [[ "$VERSION" == *"-rc"* ]]; then
-            echo "Version $VERSION is a prerelease, using 'next' tag"
+          # Check if it's a pre-release version (alpha, beta, or rc)
+          if [[ "$VERSION" == *"-alpha"* ]] || [[ "$VERSION" == *"-beta"* ]] || [[ "$VERSION" == *"-rc"* ]]; then
+            echo "Version $VERSION is a pre-release, using 'next' tag"
             echo "tag=next" >> $GITHUB_OUTPUT
           else
             echo "Version $VERSION is a stable release, using 'latest' tag"

CONTRIBUTING.md

@@ -3,6 +3,9 @@
 We welcome code contributions, feature requests, and reporting of issues. Please
 see [guidelines and instructions](.github/CONTRIBUTING.md).
 
+For information about creating releases and publishing new versions, see the
+[Release Documentation](docs/contributing/release.md).
+
 ---
 
 This repo is subdivided into 3 parts using yarn workspaces:

docs/contributing/release.md

@@ -1,21 +1,72 @@
 # Release
 
-The `@shopify/checkout-sheet-kit` module is published to the NPM package
-registry with public access.
+The `@shopify/checkout-sheet-kit` module is published to NPM with public access.
 
-In order to publish a new version of the package, you must complete the
-following steps:
+## Preparing for a release
 
-1. Bump the version in `modules/@shopify/checkout-sheet-kit/package.json` to an
-   appropriate value.
-2. Add a [Changelog](./CHANGELOG.md) entry.
-3. Merge your PR to `main`.
-4. Create a [Release](/releases) for your new version.
+Before creating a release, ensure the following version strings are updated and synchronized:
 
-Creating and publishing a Github release with begin the automated process of
-publishing the latest version of the package to NPM. It will clean the module
-folder, build a new version, run `npm pack --dry-run` to verify the contents and
-publish to the NPM registry.
+1. Bump the [package version](https://github.com/Shopify/checkout-sheet-kit-react-native/blob/main/modules/%40shopify/checkout-sheet-kit/package.json#L4)
 
-You can follow the release action process via
-https://github.com/Shopify/checkout-sheet-kit-react-native/actions/workflows/publish.yml.
+**Important**: The version in `package.json` must match the Git tag exactly, including any pre-release suffixes (e.g., `-alpha.1`, `-beta.1`, `-rc.1`).
+
+### Version format
+
+- **Production releases**: `X.Y.Z` (e.g., `3.5.0`)
+- **Pre-releases**: `X.Y.Z-{alpha|beta|rc}.N` (e.g., `3.5.0-alpha.1`, `3.5.0-beta.2`, `3.5.0-rc.1`)
+
+Pre-release suffixes ensure npm users must explicitly opt-in to install pre-release versions.
+
+## Creating a release
+
+Navigate to https://github.com/Shopify/checkout-sheet-kit-react-native/releases and click "Draft a new release", then complete the following steps:
+
+### For production releases (from `main` branch):
+
+1. Ensure you're on the `main` branch
+2. Create a tag for the new version (e.g., `3.5.0`)
+3. Use the same tag as the release title
+4. Document the full list of changes since the previous release, tagging merged pull requests where applicable
+5. ✅ Check "Set as the latest release"
+6. Click "Publish release"
+
+### For pre-releases (from non-`main` branch):
+
+1. Ensure you're on a feature/release branch (NOT `main`)
+2. Create a tag with a pre-release suffix (e.g., `3.5.0-alpha.1`, `3.5.0-beta.1`, `3.5.0-rc.2`)
+3. Use the same tag as the release title
+4. Document the changes being tested in this pre-release
+5. ✅ Check "Set as a pre-release" (NOT "Set as the latest release")
+6. Click "Publish release"
+
+## What happens after publishing
+
+When you publish a release (production or pre-release), the [publish workflow](https://github.com/Shopify/checkout-sheet-kit-react-native/actions/workflows/publish.yml) will automatically:
+
+1. **Validate versions**: Ensures `package.json` version matches the git tag
+2. **Determine npm tag**: Pre-releases (`-alpha`, `-beta`, `-rc`) publish to `next` tag, production releases publish to `latest` tag
+3. **Build and publish**: Publishes the version to npm
+
+## Using pre-releases
+
+For users to install a pre-release version:
+
+**npm** - Must specify the exact version or use the `next` tag:
+```bash
+npm install @shopify/[email protected]
+# or
+npm install @shopify/checkout-sheet-kit@next
+```
+
+**CocoaPods** - Must specify the exact version in Podfile:
+```ruby
+pod 'RNShopifyCheckoutSheetKit', '3.5.0-beta.1'
+```
+
+## Troubleshooting
+
+**Version mismatch error**: Update `package.json` to match the git tag, then recreate the release.
+
+**Pre-release not on npm**: Verify version has suffix (`-alpha.1`, `-beta.1`, `-rc.1`) and "Set as a pre-release" was checked.
+
+**Wrong npm tag**: Manually fix with `npm dist-tag add @shopify/[email protected] latest`