Versioning

Introduction

The kit is released as one set of packages that always share a version number. When you upgrade, you move every @pilotoo/* package to the same version at once, and the Changelog for that version lists what changed. These docs describe the latest release; the version menu next to the logo shows which one that is.

One version for the whole kit

These seven packages form a fixed set. A release bumps all of them together, even the ones that did not change:

Package	Side
@pilotoo/chat-protocol	both
@pilotoo/chat-core	client
@pilotoo/chat-ui	client
@pilotoo/ui	client
@pilotoo/agent-runtime	server
@pilotoo/server	server
@pilotoo/local-server	server

Because they move together, a client built on @pilotoo/[email protected] talks to a server built on @pilotoo/[email protected]. Keep the client and server on the same version.

package.json

{
  "dependencies": {
    "@pilotoo/server": "0.1.0",
    "@pilotoo/agent-runtime": "0.1.0"
  }
}

Note

@pilotoo/voice and @pilotoo/voice-native are not part of the fixed set yet and are not packed for release. Use them from the workspace for now.

Semantic versioning

Version numbers follow Semantic Versioning: MAJOR.MINOR.PATCH.

• Patch (0.1.0 → 0.1.1): bug fixes only. Safe to take.
• Minor (0.1.x → 0.2.0): new features. Before 1.0.0, a minor release may also contain breaking changes, so read its changelog entry before you upgrade.
• Major (from 1.0.0 on): breaking changes.

Pin exact versions while the kit is below 1.0.0, and upgrade on purpose.

Workflows, Connections and Brain

Workflows, Connections and Brain are on main, but their packages are versioned on their own and are not in the tarballs that pnpm release:check packs. Their APIs can still change between versions; the changelog lists what changed.

Upgrading

1. Read the Changelog entries between your version and the new one.
2. Bump every @pilotoo/* package to the new version in one change.
3. Run your type checker. A renamed or removed option of PilotooModule.forRoot, ChatProvider or another kit API shows up as a type error.
4. Run your tests against a real conversation before you deploy.

Contributing a change

The kit uses Changesets to version releases. Every pull request that changes a package adds a changeset describing the change for the changelog:

pnpm changeset

Pick the packages you changed and the bump type. The fixed set takes care of bumping the others. Before a release, pnpm release:check builds and packs the seven packages and inspects the tarballs.