Skip to content

RELEASING.md

Latest commit

 

History

History
135 lines (97 loc) · 4.03 KB

RELEASING.md

File metadata and controls

135 lines (97 loc) · 4.03 KB
Raw

Releasing & Publishing

This repository uses Changesets for versioning and npm publishing. Each extension package is versioned independently.

How it works

Make changes → Add changeset → Push to master → CI opens "Version Packages" PR → Merge PR → Packages published to npm

1. Add a changeset

After making changes to one or more extensions, run:

pnpm changeset

This interactive CLI will ask:

  • Which packages changed? Select the affected extension(s)
  • What kind of bump? patch (bug fix), minor (new feature), or major (breaking change)
  • Summary: A short description of the change

This creates a markdown file in .changeset/ describing the change. Commit it with your code.

2. Push to master

git add .
git commit -m "feat: add new search provider"
git push origin master

3. CI creates a "Version Packages" PR

The release.yml GitHub Action detects pending changesets and opens a PR titled "chore: version packages". This PR:

  • Bumps version in each affected package.json
  • Generates/updates CHANGELOG.md for each package
  • Removes the consumed .changeset/*.md files

4. Merge the PR to publish

When you merge the "Version Packages" PR, the action runs pnpm run release which:

  • Publishes each bumped package to npm under the @framers scope
  • Creates GitHub releases with tags like @framers/agentos-ext-web-search@1.2.0
  • Updates registry.json with the latest versions

Version bump guide

Change type Bump Example
Bug fix, typo, perf improvement patch 1.0.0 -> 1.0.1
New feature, new tool, new export minor 1.0.0 -> 1.1.0
Breaking API change, removed export major 1.0.0 -> 2.0.0

Multiple changes in one PR

You can include multiple changesets in a single commit or PR. Each changeset can target different packages with different bump types:

# First changeset: patch for web-search
pnpm changeset
# Select @framers/agentos-ext-web-search, patch

# Second changeset: minor for telegram
pnpm changeset
# Select @framers/agentos-ext-telegram, minor

Manual publishing (emergency)

If CI is broken and you need to publish manually:

# Ensure you have NPM_TOKEN set
export NPM_TOKEN=npm_xxxx

# Version the packages (applies changesets)
pnpm run version-packages

# Review the changes, then publish
pnpm run release

Adding a new extension

When adding a new extension package:

  1. Create the package in registry/curated/<category>/<name>/
  2. Add it to pnpm-workspace.yaml
  3. Ensure package.json has:
    • "private": false (or omit the field)
    • "publishConfig": { "access": "public" }
    • Correct "name" under @framers/ scope
  4. Add an initial changeset: pnpm changeset and select the new package with a minor bump

Secrets

Secret Where Purpose
GITHUB_TOKEN Automatic PR creation, GitHub releases
NPM_TOKEN Repository Settings > Secrets > Actions npm publishing for @framers scope

The NPM_TOKEN must be a granular access token with publish permissions for the @framers organization. Generate one at npmjs.com/settings/tokens.

Workspace packages

The pnpm-workspace.yaml lists all publishable packages:

packages:
  - "registry/curated/auth"
  - "registry/curated/provenance/anchor-providers"
  - "registry/curated/research/web-search"
  - "registry/curated/research/web-browser"
  - "registry/curated/integrations/telegram"
  - "registry/curated/communications/telegram-bot"
  - "registry/curated/system/cli-executor"

Changesets config

The .changeset/config.json controls behavior:

{
  "changelog": ["@changesets/changelog-github", { "repo": "framerslab/agentos-extensions" }],
  "access": "public",
  "baseBranch": "master"
}
  • changelog: Auto-links PRs and commits in changelogs
  • access: All packages publish as public
  • baseBranch: Changesets tracks changes against master