Releasing

Releases are published by GitHub Actions (.github/workflows/release.yml) when a version tag is pushed.

One-time setup

The workflow uses npm trusted publishing (OIDC), so there is no npm token to create or rotate. On npmjs.com, open the package → Settings → Trusted Publisher → GitHub Actions and enter owner fourlyn, repository apple-foundation-models, workflow release.yml.

Cut a release

Update CHANGELOG.md: rename the top section to the new version, e.g. ## 0.2.0 — 2026-10-15. The workflow copies the section whose heading starts with that version into the GitHub release notes.
Set the same version in src/models.ts (PACKAGE_VERSION).
Bump package.json and create the tag:
```
npm version minor        # or patch / major / 1.0.0-beta.1
git push --follow-tags
```
npm version commits package.json and tags vX.Y.Z. Commit the changelog and PACKAGE_VERSION changes first, or stage them and use npm version minor --force.

What the workflow does

Step	Fails the release when
Version check	the tag, `package.json` and `PACKAGE_VERSION` disagree
`npm run typecheck`, `npm test`, `npm run build`	anything fails
`npm publish --access public --provenance`	the trusted publisher is not configured (skipped if the version is already on npm)
GitHub release	— (notes come from `CHANGELOG.md`)

Pre-release versions (anything with a -, such as 1.0.0-beta.1) are published under the npm tag next and marked as pre-releases on GitHub, so npm install @fourlyn/apple-foundation-models keeps resolving to the latest stable version.

Versioning

Semantic Versioning. While the version is 0.x, minor versions may contain breaking changes; say so in the changelog. Apple SDK support changes (a new minimum Xcode, a renamed Apple API) are breaking changes.

Before tagging

Run the checks in testing.md: the three automated suites, then the Self-Test on a physical device. The workflow runs only the JS suite; the Swift tests and the example build run in CI on every push.