From e4de9e843339a2f1ca352f257bec8ce78055b21a Mon Sep 17 00:00:00 2001 From: James Martinez Date: Fri, 17 Apr 2026 17:03:16 -0500 Subject: [PATCH 1/2] docs: add releases doc --- packages/docs/docs.json | 1 + packages/docs/docs/releases.mdx | 62 +++++++++++++++++++++++++++++++++ packages/openworkflow/README.md | 1 + 3 files changed, 64 insertions(+) create mode 100644 packages/docs/docs/releases.mdx diff --git a/packages/docs/docs.json b/packages/docs/docs.json index 4d34e3bf..f7559bc1 100644 --- a/packages/docs/docs.json +++ b/packages/docs/docs.json @@ -73,6 +73,7 @@ { "group": "Resources", "pages": [ + "docs/releases", "docs/migration-v6", "docs/roadmap", "docs/llms", diff --git a/packages/docs/docs/releases.mdx b/packages/docs/docs/releases.mdx new file mode 100644 index 00000000..0108c371 --- /dev/null +++ b/packages/docs/docs/releases.mdx @@ -0,0 +1,62 @@ +--- +title: Releases +description: How we version OpenWorkflow while we're still pre-1.0 +--- + +OpenWorkflow is pre-1.0. The API is still settling, and we'd rather say that out +loud than pretend otherwise. This page explains what that means for you in +practice, and why we've set things up this way. + +## The short version + +While we're on `0.y.z`, **breaking changes ship in the minor**, not the major. +Everything else - new features, bug fixes, performance work - ships in the +patch. + +``` +0.9.0 → 0.9.1 safe bug fix or new feature +0.9.1 → 0.9.2 safe bug fix or new feature +0.9.2 → 0.10.0 break read the changelog before you upgrade +``` + +Each package in the repo (`openworkflow`, `@openworkflow/cli`, the dashboard) +versions independently. A breaking change in the CLI bumps the CLI's minor; it +doesn't force a bump elsewhere. + +## Upgrading safely + +The good news: npm's default behavior already does the right thing. `^0.9.0` in +your `package.json` resolves to `>=0.9.0 <0.10.0`. You will **not** silently +pick up a breaking `0.10.0` during a routine `npm install`. You have to opt in. + +## Why we do it this way + +We want one honest signal in the version number, and we want to stay free to fix +design mistakes while the project is young. Those two goals pull in opposite +directions under strict semver - going to 1.0 would lock us in, staying on 0.x +without a convention would give you no way to tell a safe upgrade from a risky +one. + +The 0.y.z-breaks-in-minor convention is the common compromise for semver. Cargo +formalizes this exact rule for the Rust ecosystem, and React Native runs the +same policy and has for years. We're in good company. + +Starting at 1.0 instead would be the dishonest option. Projects that do it +usually end up either cranking through majors (`2.0`, `3.0`, `4.0` in a year, +which makes the major meaningless) or quietly breaking things inside minors +(which makes semver meaningless). We'd rather be upfront about where we are. + +FWIW this is a solid counter-argument and worth reading if you're making this +call in your own project: [Jon Skeet on starting at 1.0 +instead](https://codeblog.jonskeet.uk/2019/10/20/why-i-dont-start-versions-at-0-x-any-more/). + +## When we'll hit 1.0 + +1.0 is a gate, not a timeline. We'll ship it when: + +- The workflow, step, and worker APIs have stayed shape-stable across two + consecutive minor releases. +- The backend interface is stable enough that you could write your own backend + without reading our source. + +After 1.0, changes will follow standard semver. diff --git a/packages/openworkflow/README.md b/packages/openworkflow/README.md index ccb0229d..fa534cc3 100644 --- a/packages/openworkflow/README.md +++ b/packages/openworkflow/README.md @@ -63,6 +63,7 @@ started. - [Core Concepts](https://openworkflow.dev/docs/overview) - [Advanced Patterns](https://openworkflow.dev/docs/advanced-patterns) - [Production Checklist](https://openworkflow.dev/docs/production) +- [Releases](https://openworkflow.dev/docs/releases) ## Architecture From 4117030d82939b574f86e84dbc801df79797230e Mon Sep 17 00:00:00 2001 From: James Martinez Date: Fri, 17 Apr 2026 17:06:24 -0500 Subject: [PATCH 2/2] Update packages/docs/docs/releases.mdx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- packages/docs/docs/releases.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/docs/docs/releases.mdx b/packages/docs/docs/releases.mdx index 0108c371..b9be42c5 100644 --- a/packages/docs/docs/releases.mdx +++ b/packages/docs/docs/releases.mdx @@ -20,8 +20,8 @@ patch. ``` Each package in the repo (`openworkflow`, `@openworkflow/cli`, the dashboard) -versions independently. A breaking change in the CLI bumps the CLI's minor; it -doesn't force a bump elsewhere. +is versioned independently. A breaking change in the CLI bumps the CLI's minor; +it doesn't force a bump elsewhere. ## Upgrading safely