From b7fddd130761ad7fbdf8e00325c3ded6f625780d Mon Sep 17 00:00:00 2001 From: Westin Wrzesinski Date: Tue, 11 Nov 2025 18:18:26 -0600 Subject: [PATCH] Update Publish docs and add alpha releases 1. Update documenation for releases and include link in contributing guide 2. Add support for `alpha` releases to the publishing action --- .github/workflows/publish.yml | 38 ++++++++++++++-- CONTRIBUTING.md | 3 ++ docs/contributing/release.md | 81 ++++++++++++++++++++++++++++------- 3 files changed, 104 insertions(+), 18 deletions(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 49591497..04eb3697 100644 --- a/.github/workflows/publish.yml +++ b/.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" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c316e73a..84960ec0 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/docs/contributing/release.md b/docs/contributing/release.md index 3e478044..62387c63 100644 --- a/docs/contributing/release.md +++ b/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/checkout-sheet-kit@3.5.0-beta.1 +# 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/checkout-sheet-kit@3.5.0 latest`