diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index a679429..922559d 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -1,3 +1,4 @@ +# Ensures a changeset is present on PRs. Skip with the "🤖Skip Changelog" label. name: Changelog on: diff --git a/.github/workflows/check-cdn-types.yml b/.github/workflows/check-cdn-types.yml index a8ae0e3..e17df0c 100644 --- a/.github/workflows/check-cdn-types.yml +++ b/.github/workflows/check-cdn-types.yml @@ -1,3 +1,5 @@ +# Detects changes between the CDN-hosted App Bridge types and the published +# @shopify/app-bridge-types npm package, and opens a PR when they differ. name: Check CDN Types on: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3a4aceb..0f8277c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,3 +1,4 @@ +# Runs formatting, build, lint, type-check, and tests. name: CI on: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 19b27a0..8f05e64 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,3 +1,5 @@ +# Creates "Version Packages" PRs from pending changesets and publishes to npm +# when those PRs are merged. name: Release on: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..77611e0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,101 @@ +# Contributing to Shopify App Bridge + +## Table of Contents + +- [Contributing to Shopify App Bridge](#contributing-to-shopify-app-bridge) + - [Table of Contents](#table-of-contents) + - [Getting Started](#getting-started) + - [Development Workflow](#development-workflow) + - [Changesets and Versioning](#changesets-and-versioning) + - [Adding a changeset](#adding-a-changeset) + - [Skipping the changelog check](#skipping-the-changelog-check) + - [Releasing](#releasing) + - [How it works](#how-it-works) + - [Summary](#summary) + - [Package-Specific Guides](#package-specific-guides) + +## Getting Started + +```bash +# Clone the repo +git clone git@github.com:Shopify/shopify-app-bridge.git +cd shopify-app-bridge + +# Install dependencies (requires pnpm ≥ 10) +pnpm install + +# Build all packages +pnpm build +``` + +The required Node.js version is specified in `.nvmrc`. + +## Development Workflow + +1. **Create a branch** off `main` for your changes. +2. **Make your changes** in the relevant package(s). +3. **Run checks locally** before pushing: + ```bash + pnpm format:check # Prettier formatting + pnpm build # Build all packages + pnpm lint # Lint all packages + pnpm type-check # TypeScript type checking + pnpm test # Run tests + ``` +4. **Add a changeset** describing your changes (see below). +5. **Open a pull request** against `main`. CI will run all checks automatically. + +## Changesets and Versioning + +This repo uses [Changesets](https://github.com/changesets/changesets) to manage versioning and changelogs. Every PR that changes package behavior should include a changeset. + +### Adding a changeset + +```bash +pnpm changeset +``` + +This will prompt you to: + +1. Select which package(s) are affected. +2. Choose a semver bump type (`patch`, `minor`, or `major`). +3. Write a summary of the change (this becomes the changelog entry). + +A markdown file will be created in `.changeset/`. Commit it with your PR. + +### Skipping the changelog check + +If your PR doesn't need a changeset (e.g. docs-only, CI config), add the **🤖Skip Changelog** label to the PR to bypass the changelog CI check. + +## Releasing + +Releases are fully automated via the [Release workflow](.github/workflows/release.yml). + +### How it works + +1. When PRs with changesets are merged to `main`, the Release workflow runs. +2. The [changesets/action](https://github.com/changesets/action) collects all pending changesets and opens a **"Version Packages"** PR that: + - Bumps package versions in `package.json` files. + - Updates `CHANGELOG.md` files with the changeset summaries. + - Removes the consumed `.changeset/*.md` files. +3. **When you merge the "Version Packages" PR**, the Release workflow runs again and this time publishes the updated packages to npm. + +### Summary + +```mermaid +flowchart TD + A["Feature PR
(with changeset)"] -->|merge| B[main] + B --> C[Release workflow runs] + C --> D["'Version Packages' PR opened"] + D -->|merge| E[main] + E --> F[Release workflow runs] + F --> G["Published to npm 🚀"] +``` + +> **Important:** Do _not_ manually bump versions or edit changelogs. Let Changesets handle it. + +## Package-Specific Guides + +Some packages have their own `CONTRIBUTING.md` with additional details: + +- [`packages/app-bridge-types/CONTRIBUTING.md`](packages/app-bridge-types/CONTRIBUTING.md) — `@shopify/app-bridge-types` diff --git a/packages/app-bridge-types/CONTRIBUTING.md b/packages/app-bridge-types/CONTRIBUTING.md new file mode 100644 index 0000000..3fa86f6 --- /dev/null +++ b/packages/app-bridge-types/CONTRIBUTING.md @@ -0,0 +1,41 @@ +# Contributing to `@shopify/app-bridge-types` + +See the [root CONTRIBUTING.md](../../CONTRIBUTING.md) for general repo guidelines. + +## Overview + +This package publishes TypeScript type definitions for [Shopify App Bridge](https://shopify.dev/docs/api/app-bridge). The types originate from the Shopify CDN and are repackaged here for npm consumers. + +**Source of truth:** `https://cdn.shopify.com/shopifycloud/app-bridge.d.ts` + +## How the Build Works + +The build process downloads the type definitions from the CDN rather than compiling from local source: + +1. `scripts/build.mjs` fetches `app-bridge.d.ts` from the CDN. +2. The fetched file is written to `dist/index.d.ts`. +3. The `cjyes` tool generates the CJS wrapper (`dist/index.js`) alongside `dist/index.mjs`. + +```bash +pnpm build # in this package directory +``` + +## How Types Get Updated + +There are two paths for updating the types when the App Bridge team publishes changes to the CDN. + +### Automated (daily) + +The [Check CDN Types](.github/../../.github/workflows/check-cdn-types.yml) workflow runs daily at 10:00 UTC and can also be triggered manually: + +1. `scripts/check-cdn-updates.mjs` fetches the latest CDN types and compares them against the currently published npm version. +2. If they differ, it: + - Creates a changeset (`.changeset/automated-cdn-types-update.md`). + - Opens (or updates) a PR on the `automated/update-app-bridge-types` branch. + - Uploads the raw diff as a workflow artifact (`cdn-types-diff`) for inspection. +3. A maintainer reviews the PR and pushes any changes to the PR branch as needed (e.g. editing the changeset to adjust the version bump level or changelog entry). +4. Merging the PR kicks off the normal [release process](../../CONTRIBUTING.md#releasing) — Changesets will open a "Version Packages" PR, and merging that PR publishes to npm. + +### Manual + +If you need to release ahead of the daily check, manually trigger the **Check CDN Types** workflow from the [Actions tab](https://github.com/Shopify/shopify-app-bridge/actions/workflows/check-cdn-types.yml) using the "Run workflow" button. This runs the same process as the daily check and will open a PR if the CDN types have changed.