Versioning and releases

Youj is in alpha: ready to try and build with, but the API will still change before 1.0. Every package is at 0.x, and it goes to 1.0 once the API has settled. Until then, this page is the promise.

#What a version means

Youj follows semantic versioning the way 0.x projects do. The first number stays 0 until 1.0, so the second one does the work a major version would.

The range a package manager writes, such as ^0.1.2, already stops before 0.2.0, so a plain install or update never takes a breaking release by surprise.

All the packages release together at one version: @youj/react, @youj/core, @youj/motion, @youj/icons, @youj/illustrations, @youj/loaders, @youj/miniatures, @youj/sound, @youj/mcp and the CLI, @youj/cli. Keep them on the same one; npx @youj/cli doctor tells you when they drift.

#The alpha promise

While Youj is in alpha (0.x):

• Breaking changes come only in a minor release, never in a patch.
• Every one is announced under Breaking in the changelog, with before and after code. A release that breaks something you're likely to use gets an upgrade guide.
• Deprecation comes first, wherever it's cheap. When something is replaced rather than removed (a renamed prop, a renamed value), the old name keeps working for at least one more minor release. The docs mark it. Then it goes.
• Parts labeled stable always get that deprecation step. Experimental ones may change in any minor release without one. See stability labels.

#What counts as breaking

When in doubt, it's treated as breaking.

#Upgrading between releases

Moving from one 0.x release to the next is a minor upgrade, so it can break things. The releases page has the commands. In order:

1. Read the Breaking section of every release you're skipping over, in the changelog, and follow its upgrade guide if it has one.
2. Upgrade every Youj package to the same version, then run npx @youj/cli doctor. Your ^0.1.2 range won't take 0.2.0 by itself: change it on purpose.
3. Fix what the changelog says, and what TypeScript reports. A deprecated API still works for at least one minor release, so you can upgrade first and migrate after.
4. Copied-in items stay as they are. Run npx @youj/cli add <item> --dry-run to see what the new version would change, and add it again only when you want it.

On the next channel, prereleases such as 0.2.0-next.1 may change before the release ships. Pin the exact version while you test one.

#Copy-in code is yours

What npx @youj/cli add copies into your app is your code: an upgrade never touches it. What changes between versions is what the next youj add writes.

• Copy the version you run. Each release publishes its registry items under its version number as well as the latest, so a 0.1 CLI copies 0.1's items. The CLI uses its own version, so run it at the version of your packages (npx @youj/cli@0.1.2 add …); --latest takes the latest items instead.
• Updating a copied item is a choice. Run npx @youj/cli add <item> again and review the diff before you keep it, as you would any upstream change. A youj diff <item> command, to show what changed upstream since you copied it, is planned.
• Blocks update the same way. A block is copy-in source: once added it's yours, and later changes on the site don't touch your copy. Because npx @youj/cli add copies the items of the CLI's own version, which stay archived per release, running it never breaks an existing install. Notable block changes, renames and removals are listed in the changelog.
• The changelog covers registry items too. A breaking change to a block's or component's source is listed like one to a package.

#Stability labels

Youj is in alpha, so every component, block, loader and package entry is alpha unless it says otherwise. Only the riskiest parts carry a label: experimental. You'll find it in the header of the part's docs page, and the MCP server states each part's label in its answers.

A third label, stable, is kept for the road to 1.0. Nothing carries it yet: a part moves up to stable when its API has held through a release or two with no changes asked for. A stable item depends only on stable items, and a stable entry point exports only stable items; a test enforces both. A stable part always gets the deprecation step before a breaking change, even while Youj is 0.x.

How a label is decided:

• Alpha is the default for everything that's tested: the component package (@youj/react, whose names are still being aligned across components), blocks, motion, loaders, icons, illustrations, sounds, the CLI and the MCP server.
• Experimental is for what's new or not yet covered by tests: the Data grid block, Presentation, the voice orb, the audio recorder, the WebGL backgrounds, the Lottie player, the illustration builder and Create.

Moving up never happens silently, and neither does moving down: either is a changelog entry.

The labels live in one file, stability.json at the root of the repository: a default per kind of item, the items that differ from it, and a label for each package entry.

#Deprecations

A deprecated API keeps working until the release named for its removal, at least one minor release later. Three things mark it:

• In the docs: its props table strikes it through and says what replaces it, and its page says so in prose:

• In the changelog: under Changed in the release that deprecates it, under Breaking in the one that removes it.

Mark the old path @deprecated in its JSDoc; the docs and the API reference pick it up.

#Release channels

With the CLI, npx @youj/cli@next init sets an app up on the prerelease. Put every Youj package on the same channel.

#Supported versions

Only the latest minor release gets fixes while Youj is 0.x. After 1.0, the previous major will get security fixes for a time we'll state when it ships.

#Releases and upgrade guides

Every Youj package releases together, at one version.

#What changed

• The changelog has every release, newest first, with its Breaking, Added, Changed and Fixed changes. Subscribe to its feed to hear about new ones.
• CHANGELOG.md in the repository is the same record, as one file.
• Each package's own CHANGELOG.md (packages/ui/CHANGELOG.md for @youj/react, and so on) lists every change to it, one line each, written when the release is versioned.

#Upgrading

Upgrade every Youj package at once, to the same version:

pnpm up "@youj/*" --latest
npx @youj/cli doctor

youj doctor checks the packages agree and the setup still holds. Before a minor upgrade, read its Breaking section in the changelog and follow its upgrade guide, if it has one. Deprecated APIs keep working for at least one minor release, so you can upgrade first and migrate after.

Code you copied in with npx @youj/cli add doesn't change when you upgrade. To take an item's new version, add it again and review the diff before you keep it.

To try a release before it ships, install the next channel: pnpm add @youj/react@next, with the other Youj packages on @next too.

#Upgrade guides

A minor release that breaks something you're likely to use gets a guide here: what changed and why, before and after code, the codemod to run if there is one, and the steps to do by hand.

There are none yet: 0.1.0 is the first release.