Release Process

This document describes how releases are managed in the Viber3D project.

Release Script

Viber3D uses an automated release script to handle version bumping, tagging, and publishing packages to npm. The script is located at scripts/release.ts and can be run using:

pnpm tsx scripts/release.ts [version-type] [options]

Version Types

The script supports the following version types:

• major - Bump the major version (e.g., 1.0.0 → 2.0.0)
• minor - Bump the minor version (e.g., 1.0.0 → 1.1.0)
• patch - Bump the patch version (e.g., 1.0.0 → 1.0.1)
• Specific version - Provide a specific version number (e.g., "1.2.3")

If no version type is specified, patch is used by default.

Options

The release script supports the following options:

• --alpha - Create an alpha release (e.g., 1.0.0-alpha.0)
• --package=name - Specify a package to release (default: all publishable packages)
• --no-git - Skip git commit and tag

Release Process

When the release script is run, it performs the following steps:

1. Builds all packages using pnpm build:packages
2. Bumps the version in all package.json files
3. Creates a git commit and tag for the release (unless --no-git is specified)
4. Publishes the packages to npm

Alpha Releases

Alpha releases are useful for testing new features before a stable release. They are published with the alpha tag on npm, which means they won't be installed by default when users run npm install viber3d.

To create an alpha release:

pnpm tsx scripts/release.ts --alpha

This will create a version like 1.0.0-alpha.0 and publish it with the alpha tag.

Publishing Workflow

The typical workflow for publishing a new release is:

1. Make sure all changes are committed and pushed to the repository
2. Run the release script with the appropriate version type:

   pnpm tsx scripts/release.ts minor
   

3. The script will handle version bumping, git tagging, and publishing to npm

Versioning Strategy

Viber3D follows Semantic Versioning (SemVer):

• Major version (x.0.0): Breaking changes that require updates to user code
• Minor version (0.x.0): New features added in a backward-compatible manner
• Patch version (0.0.x): Backward-compatible bug fixes

Templates and Releases

When releasing new versions, consider whether template updates are needed:

• The default starter template should be updated for stable releases
• The starter-next template (accessed via the next branch) can be used for testing upcoming features

Users can access the experimental template using:

npx viber3d@latest init my-game --template next

This will use the template from templates/starter-next on the next branch.

Release Checklist

Before creating a release:

1. Ensure all tests pass
2. Update documentation to reflect any changes
3. Update the changelog with notable changes
4. Make sure all changes are committed and pushed
5. Run the release script with the appropriate version type