From 7a0e71c22c6746f358497e3a3fe5bf60c78e6eee Mon Sep 17 00:00:00 2001 From: Andre Wiggins Date: Thu, 2 Apr 2026 15:59:44 -0700 Subject: [PATCH 1/2] Add contributing guides for maintainers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add CONTRIBUTING.md files at the repo root and in each package to document the development workflow, release process, and automation for Shopify engineers maintaining this monorepo. Root guide covers: - Getting started and local development setup - How Changesets manages versioning and changelogs - The two-step automated release flow (Version Packages PR β†’ npm publish) - Overview of all CI/automation workflows Package guides cover: - app-bridge-types: CDN-based build process, automated daily type update workflow, and manual release steps - app-bridge-react: Vite build setup, testing, and dependency relationship with app-bridge-types --- .github/workflows/changelog.yml | 1 + .github/workflows/check-cdn-types.yml | 2 + .github/workflows/ci.yml | 1 + .github/workflows/release.yml | 2 + CONTRIBUTING.md | 99 +++++++++++++++++++++++ packages/app-bridge-types/CONTRIBUTING.md | 41 ++++++++++ 6 files changed, 146 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 packages/app-bridge-types/CONTRIBUTING.md diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index c17219d..16e903a 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 4a81db9..3df403b 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 c319aa1..e2b58fe 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 ce49d17..eb1cdb4 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..d13b99f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Contributing to Shopify App Bridge + +## Table of Contents + +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Changesets and Versioning](#changesets-and-versioning) +- [Releasing](#releasing) +- [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 + +``` +Feature PR (with changeset) ──merge──▢ main + β”‚ + Release workflow runs + β”‚ + "Version Packages" PR opened + β”‚ + ──merge──▢ main + β”‚ + Release workflow runs + β”‚ + 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. From 42a9746cefacc87adf38d98ddad5dc49f98a2be8 Mon Sep 17 00:00:00 2001 From: Andre Wiggins Date: Fri, 3 Apr 2026 09:58:12 -0700 Subject: [PATCH 2/2] Replace ASCII release diagram with Mermaid flowchart in CONTRIBUTING.md --- CONTRIBUTING.md | 36 +++++++++++++++++++----------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d13b99f..77611e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,11 +2,17 @@ ## Table of Contents -- [Getting Started](#getting-started) -- [Development Workflow](#development-workflow) -- [Changesets and Versioning](#changesets-and-versioning) -- [Releasing](#releasing) -- [Package-Specific Guides](#package-specific-guides) +- [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 @@ -76,18 +82,14 @@ Releases are fully automated via the [Release workflow](.github/workflows/releas ### Summary -``` -Feature PR (with changeset) ──merge──▢ main - β”‚ - Release workflow runs - β”‚ - "Version Packages" PR opened - β”‚ - ──merge──▢ main - β”‚ - Release workflow runs - β”‚ - Published to npm πŸš€ +```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.