Add contributing guides for maintainers

.github/workflows/changelog.yml

@@ -1,3 +1,4 @@
+# Ensures a changeset is present on PRs. Skip with the "🤖Skip Changelog" label.
 name: Changelog
 
 on:

.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:

.github/workflows/ci.yml

@@ -1,3 +1,4 @@
+# Runs formatting, build, lint, type-check, and tests.
 name: CI
 
 on:

.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:

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<br>(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`

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.