chore: bootstrap release-please + project conventions

jaymaycry · claude · jaymaycry · commit 1b69bda585c9 · 2026-05-19T21:21:08.000+02:00
Replaces the previous release workflow with release-please-action, wired
to publish via npm Trusted Publishing (OIDC) on tag creation. The
manifest pins the current version at 0.1.0 with bootstrap-sha set to
the last commit before automated releases started, so the next release
PR will pick up the iOS fix as 0.1.1.

Adds AGENTS.md (Conventional Commits rules, release flow, things to
avoid) and CLAUDE.md as a pointer to it, plus a Releasing section in
README, so future contributors and agents follow the same conventions.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
@@ -1,18 +1,35 @@
-name: Release
+name: Release Please
 
 on:
   push:
-    tags:
-      - 'v*'
+    branches: [main]
 
 permissions:
-  contents: read
-  id-token: write
+  contents: write
+  pull-requests: write
 
 jobs:
+  release-please:
+    name: Release PR / tag
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
   publish:
     name: Publish to npm
+    needs: release-please
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -27,15 +44,6 @@ jobs:
       - name: Install dependencies
         run: yarn install --frozen-lockfile
 
-      - name: Verify tag matches package.json version
-        run: |
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          TAG_VERSION="${GITHUB_REF_NAME#v}"
-          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
-            echo "Tag $GITHUB_REF_NAME (version $TAG_VERSION) does not match package.json version $PKG_VERSION"
-            exit 1
-          fi
-
       - name: Build
         run: yarn prepare
 
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,101 @@
+# AGENTS.md
+
+Project conventions for AI coding agents working in this repo. Read this
+before making changes — most of it is not derivable from the code alone.
+
+## What this repo is
+
+A React Native Turbo Module (`@panter/react-native-motiontag`) wrapping
+the MotionTag tracking SDKs (iOS 6.5.x, Android 7.2.x). New architecture
+only. JS surface mirrors the official Flutter SDK so payloads stay
+interchangeable.
+
+Repo layout: see [README.md → Repo layout](README.md#repo-layout).
+
+## Commit conventions
+
+This repo uses [Conventional Commits](https://www.conventionalcommits.org/),
+enforced by release-please. **Every commit subject to `main` must follow the
+format** or it won't appear in the changelog and may break automated
+versioning.
+
+| Prefix | Meaning | Version bump |
+| --- | --- | --- |
+| `feat:` | New user-facing feature | minor |
+| `fix:` | Bug fix | patch |
+| `feat!:` / `fix!:` / `BREAKING CHANGE:` body | Breaking change | major |
+| `chore:` | Tooling, deps, internal cleanup | none |
+| `docs:` | Documentation only | none |
+| `refactor:` | Internal restructure, no behaviour change | none |
+| `test:` | Test-only changes | none |
+| `ci:` | CI / workflow changes | none |
+| `build:` | Build system changes | none |
+
+Optional scope in parentheses: `feat(plugin): add channelId option`,
+`fix(android): handle null permission result`.
+
+Do **not** add a trailing summary paragraph in commit bodies that repeats
+the subject. Body explains *why*; subject already says *what*.
+
+## Release flow
+
+Releases are automated — agents must not run `npm publish` directly or
+push tags manually. See [README → Releasing](README.md#releasing) for the
+full flow. TL;DR: commit with Conventional Commits → release-please opens
+a release PR → merging it tags + publishes via GitHub Actions OIDC.
+
+## Working with the code
+
+- **Library source**: `src/` — TypeScript, no transpilation in the example
+  (uses the `react-native` field in `package.json` to consume `src/` directly).
+- **Native modules**: `android/` (Kotlin) and `ios/` (Swift + ObjC++).
+  Changing the TS spec (`src/NativeMotionTag.ts`) regenerates the codegen
+  contract — both native sides must be updated to match.
+- **Expo config plugin**: `plugin/` (plain JS, no build). Injected blocks
+  are wrapped in `@generated` markers and de-duplicated on `expo prebuild`
+  re-runs.
+- **Example app**: `example/` is a Standalone Expo dev-client app. It
+  declares the library via `"file:.."` so edits to `src/` hot-reload via
+  Fast Refresh. Metro config in `example/metro.config.js` blocks duplicate
+  `react` / `react-native` copies — do not change without understanding
+  why.
+
+## Build / verify
+
+- TypeScript build: `yarn prepare` (runs `react-native-builder-bob`,
+  outputs `lib/{commonjs,module,typescript}`).
+- Typecheck only: `npx tsc -p tsconfig.build.json --noEmit`.
+- Lint: none configured yet. Don't add one without asking.
+- Tests: none yet. Don't add a test framework speculatively.
+- The CI workflow (`.github/workflows/ci.yml`) runs `yarn prepare` on PRs;
+  if your change touches `src/`, make sure it builds cleanly locally first.
+
+## What to avoid
+
+- Don't bump `version` in `package.json` by hand — release-please owns it.
+- Don't edit `CHANGELOG.md` by hand — release-please owns it.
+- Don't edit `.release-please-manifest.json` unless intentionally
+  bootstrapping (extremely rare).
+- Don't add a `prepublishOnly` or other publish-side hook that would race
+  with `prepare` in the GitHub Actions workflow.
+- Don't add Expo Go support — the library has native code and requires a
+  development client build. Documentation that suggests otherwise is wrong.
+- Don't align the iOS and Android SDK versions opportunistically. Version
+  drift is intentional pending a separate evaluation (tracked as a
+  follow-up). Touch only when explicitly asked.
+- Don't introduce a monorepo tool (Lerna, Nx, Turborepo). The
+  library + `example/` two-package layout is deliberate.
+
+## Native dependency versions
+
+Hard-coded; see [README → Native dependency versions](README.md#native-dependency-versions).
+Bumping these is a feature change with cross-platform implications —
+treat as a `feat:` (or `feat!:` if API-incompatible) and update both
+platforms in the same PR.
+
+## When in doubt
+
+Ask. The MotionTag SDK has thin, sometimes surprising native contracts
+(pre-RN init requirements, background task identifiers, foreground-service
+ownership) that aren't obvious from the JS surface — better to confirm
+than to guess.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,4 @@
+# CLAUDE.md
+
+See [AGENTS.md](AGENTS.md) for project conventions, commit format, release
+flow, and what to avoid when making changes in this repo.
diff --git a/README.md b/README.md
@@ -18,6 +18,7 @@ SDK v7.2.x — the platform asymmetry is hidden behind a shared TS contract.
 - [Running the example app](#running-the-example-app)
 - [Repo layout](#repo-layout)
 - [Developing the package](#developing-the-package)
+- [Releasing](#releasing)
 
 ## Install in your app
 
@@ -266,3 +267,54 @@ re-install.
 - **Iterate on the Expo config plugin** by editing files in `plugin/` and
   re-running `npx expo prebuild --clean` in `example/`. The injected blocks
   are wrapped in `@generated` markers and de-duplicated on re-run.
+
+## Releasing
+
+Releases are fully automated via [release-please](https://github.com/googleapis/release-please)
+and npm Trusted Publishing — no manual `npm publish`, no tokens, no
+hand-edited changelog.
+
+### The flow
+
+1. Land commits on `main` using [Conventional Commits](https://www.conventionalcommits.org/):
+   - `feat: …` — minor bump (`0.1.0` → `0.2.0`)
+   - `fix: …` — patch bump (`0.1.0` → `0.1.1`)
+   - `feat!: …` or `BREAKING CHANGE:` in body — major bump
+   - `chore:`, `docs:`, `refactor:`, `test:`, `ci:` — no bump, but appear
+     in the changelog under their respective sections
+2. The **Release Please** workflow opens (or updates) a PR titled
+   `chore(main): release X.Y.Z`. The PR contains the version bump in
+   `package.json`, an updated `CHANGELOG.md` assembled from the commit
+   subjects since the last release, and an updated
+   `.release-please-manifest.json`.
+3. Merge that PR when you're ready to release. Release-please then creates
+   the git tag (`vX.Y.Z`) and a matching GitHub Release with the changelog
+   body.
+4. The `publish` job in the same workflow runs `yarn prepare` (bob build)
+   and `npm publish` with npm provenance attached via OIDC.
+
+### One-time npm setup
+
+On npmjs.com → `@panter/react-native-motiontag` → *Settings* →
+*Trusted Publisher* → *Add*:
+
+- Publisher: GitHub Actions
+- Organization: `panter`
+- Repository: `react-native-motiontag`
+- Workflow filename: `release-please.yml`
+- Environment: *(leave blank)*
+
+No `NPM_TOKEN` secret is required.
+
+### Hotfix / manual override
+
+If you need to publish a version that release-please can't produce (e.g. a
+hotfix from a non-`main` branch), bump `package.json` + push manually:
+
+```sh
+yarn prepare
+npm publish --access public
+```
+
+You'll need a local npm auth token for the manual path — Trusted
+Publishing only covers the GitHub Actions workflow.
diff --git a/release-please-config.json b/release-please-config.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "node",
+      "package-name": "@panter/react-native-motiontag",
+      "changelog-path": "CHANGELOG.md",
+      "include-component-in-tag": false,
+      "bootstrap-sha": "2f359f499f13bf49c42c7ab2c648c96fe94420c0"
+    }
+  }
+}
