Skip to content

Release & Versioning Strategy

This repository follows a structured release strategy with the following principles:

  • Long-term API stability: Avoid breaking changes in OSS and Cloud for as long as practical
  • Major bumps = marketing: 2.0.0, 3.0.0 used sparingly; not necessarily breaking
  • Patch digit always 0: All normal changes use minor bumps (x.y.0) to minimize maintenance burden (postpone patch version complexity for as long as possible)
  • Publishable packages (owox, @owox/backend, @owox/connectors always share identical versions.
NamingVersion Examplenpm tagContainer tagAudience
Release0.7.0, 1.8.0latestlatestCommunity
Snapshot0.5.0-next-20250630211639—nextCloud

Snapshots are published as container images only. They are not published to npm: every merge to main added a version to each package’s registry metadata, and @owox/backend grew large enough that npm needed up to fifteen minutes to serve a newly published version, which is time the image build spent waiting. Because npm forbids unpublishing, that metadata could only ever grow.

This covers every released package. @owox/plugin-sdk, @owox/api-client and @owox/ctl are not in the container image, so they have no snapshot channel at all — changes to them reach consumers in a release.

NeedCommand
Release (newest)npm install -g owox
Release (exact)npm install -g owox@1.8.0
Snapshot (newest)docker pull ghcr.io/owox/owox-data-marts:next
Snapshot (exact)docker pull ghcr.io/owox/owox-data-marts:0.5.0-next-20250630211639

A changeset is a release note for a change to shipped product behavior. Decide whether one is required from the observable release impact, not merely from the files or packages touched by the implementation.

Create a changeset when a release includes something users or operators need to know, including:

  • new or changed user-visible functionality or workflows;
  • a bug fix whose effect is visible to users;
  • a change to a public API, CLI, configuration, environment variable, schema, or integration contract;
  • compatibility, migration, or deployment behavior that requires user or operator awareness.

Do not create a changeset for a change that has no observable release impact, such as:

  • tests, formatting, or generated-file maintenance only;
  • an internal refactor with no behavior or contract change;
  • CI, local developer tooling, or agent-instruction changes only;
  • documentation-only changes that do not alter a shipped package.

If a pull request combines internal work with a release-relevant outcome, create a changeset for the release-relevant outcome only.

For OWOX-managed work, name every new changeset:

.changeset/<fibery-public-id>-<short-kebab-case-summary>.md

Use the public numeric ID of the Fibery Work Item that owns the release outcome described by that file. If a pull request delivers separate outcomes owned by different Work Items, create a separate changeset for each outcome that needs a release note.

Resolve the ID from explicit task context, such as a supplied Fibery link or an unambiguous pull-request or branch reference. If a changeset is required but the owning ID is still unknown or ambiguous, ask the user or responsible maintainer before creating or renaming the file. Never guess an ID, substitute a pull request number, or keep the random filename generated by npx changeset.

After running npx changeset, rename its generated file to this convention before committing it. Apply the rule to new changesets; do not rename an existing changeset without first confirming its owning Work Item.

Write the changeset title and body in user-facing language. Explain what changed and its practical effect; omit implementation detail that does not help a user understand the release.

Terminal window
# Make your changes
# Create a changeset only when the policy above requires one
npx changeset
# Rename the generated file to start with the owning Fibery Work Item ID
# Choose the appropriate bump type:
# - major: for breaking changes (use sparingly)
# - minor: for new features, improvements (recommended)
# - patch: not used in this strategy
# Add everything and commit
git add .
git commit -m "feat: your feature description"
git push

On every push to main:

  1. Snapshot Build (publish.yml): Automatically builds and pushes a snapshot container image to the next tag for testing and early access. The image is built from tarballs packed in the same job, so it never waits on the npm registry
  2. Release Build (publish.yml): When the “Version Packages” PR is merged, the workflow publishes the new release version to the latest tag
  3. Version PR (release-pr.yml): Changesets bot creates/updates a “Version Packages” PR that collects all pending changesets

A release is the merge of the “Version Packages” PR. The merge publishes the packages to npm and the container image to the latest tag. npm forbids unpublishing, so the merge is final. OWOX Cloud runs snapshots, so a release needs no deployment.

  1. Announce it. Tell the maintainers a release is coming and ask whether anything blocks it. From this point nobody merges into main until step 6. The releaser decides whether a reported blocker holds the release.
  2. Run the checks. The bot opens the PR from changeset-release/main, so its workflow runs wait as action_required. Re-run Code Quality root, Code Quality OWOX and Test and Build @owox/docs with gh run rerun <run-id>. The PR changes only changelogs, package versions and package-lock.json, so Test OWOX, the E2E suites and Audit all repeat what main already ran and can be cancelled.
  3. Read the changelog. Read the new section of apps/owox/CHANGELOG.md in the PR. The bot reformats the whole file with Prettier on every update. If an inline code span wraps across lines, every pass indents the following lines further, until markdownlint fails with MD046. Fix the original entry with a regular PR to main; the bot then regenerates the release PR.
  4. Merge. Approve and merge the PR.
  5. Wait for the publish. publish.yml keeps only the newest pending run, so a merge right behind the release can replace the release run. Wait until the Snapshot run on the release commit succeeds, then check that npm view owox dist-tags.latest prints the new version and that the <version> and latest tags of ghcr.io/owox/owox-data-marts share one digest (docker buildx imagetools inspect). If the image is missing, the run logs a warning with the recovery: start Snapshot from workflow_dispatch with rebuild_latest_image, from a ref whose HEAD is the release commit.
  6. Announce that it is out. Tell the maintainers the release is published and main is open again.
  • Never commit API keys or sensitive configuration
  • Use environment variables for configuration
  • Security audit runs automatically during the publishing process
  • Vulnerabilities are automatically detected and reported

If you encounter issues with the automated publishing:

  1. Check the GitHub Actions workflow runs in the repository
  2. Verify that all tests and linting pass locally
  3. Contact the maintainers if the automated process fails