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/connectorsalways share identical versions.
Version & Distribution Tags
Section titled âVersion & Distribution Tagsâ| Naming | Version Example | npm tag | Container tag | Audience |
|---|---|---|---|---|
| Release | 0.7.0, 1.8.0 | latest | latest | Community |
| Snapshot | 0.5.0-next-20250630211639 | â | next | Cloud |
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.
Installation Commands
Section titled âInstallation Commandsâ| Need | Command |
|---|---|
| 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 |
Changeset Policy
Section titled âChangeset Policyâ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.
When a Changeset Is Required
Section titled âWhen a Changeset Is Requiredâ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.
When a Changeset Is Not Required
Section titled âWhen a Changeset Is Not Requiredâ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.
Fibery ID and Filename
Section titled âFibery ID and FilenameâFor OWOX-managed work, name every new changeset:
.changeset/<fibery-public-id>-<short-kebab-case-summary>.mdUse 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.
Contributor Workflow
Section titled âContributor Workflowâ1. Making Changes
Section titled â1. Making Changesâ# Make your changes# Create a changeset only when the policy above requires onenpx 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 commitgit add .git commit -m "feat: your feature description"git push2. Automated Process
Section titled â2. Automated ProcessâOn every push to main:
- Snapshot Build (
publish.yml): Automatically builds and pushes a snapshot container image to thenexttag for testing and early access. The image is built from tarballs packed in the same job, so it never waits on the npm registry - Release Build (
publish.yml): When the âVersion Packagesâ PR is merged, the workflow publishes the new release version to thelatesttag - Version PR (
release-pr.yml): Changesets bot creates/updates a âVersion Packagesâ PR that collects all pending changesets
Cutting a Release
Section titled âCutting a Releaseâ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.
- Announce it. Tell the maintainers a release is coming and ask whether
anything blocks it. From this point nobody merges into
mainuntil step 6. The releaser decides whether a reported blocker holds the release. - Run the checks. The bot opens the PR from
changeset-release/main, so its workflow runs wait asaction_required. Re-run Code Quality root, Code Quality OWOX and Test and Build @owox/docs withgh run rerun <run-id>. The PR changes only changelogs, package versions andpackage-lock.json, so Test OWOX, the E2E suites and Audit all repeat whatmainalready ran and can be cancelled. - Read the changelog. Read the new section of
apps/owox/CHANGELOG.mdin 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 tomain; the bot then regenerates the release PR. - Merge. Approve and merge the PR.
- Wait for the publish.
publish.ymlkeeps 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 thatnpm view owox dist-tags.latestprints the new version and that the<version>andlatesttags ofghcr.io/owox/owox-data-martsshare one digest (docker buildx imagetools inspect). If the image is missing, the run logs a warning with the recovery: start Snapshot fromworkflow_dispatchwithrebuild_latest_image, from a ref whose HEAD is the release commit. - Announce that it is out. Tell the maintainers the release is published
and
mainis open again.
Security
Section titled âSecurityâ- 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
Troubleshooting
Section titled âTroubleshootingâIf you encounter issues with the automated publishing:
- Check the GitHub Actions workflow runs in the repository
- Verify that all tests and linting pass locally
- Contact the maintainers if the automated process fails