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.

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

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

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

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

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

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.

Contributor Workflow

1. Making Changes

# 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

2. Automated Process

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

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

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