How to Bump the Version for a Release in text-to-cad

The canonical version for the text-to-cad project is stored in plugins/cad/VERSION, and you should always use the scripts/release/bump-version.sh script to modify it rather than editing the file manually.

Bumping the version in the earthtojake/text-to-cad repository requires understanding its single-source-of-truth architecture. The project uses a centralized versioning strategy where one file drives all downstream package metadata. This guide explains the exact files, scripts, and commands needed to safely increment versions for major, minor, or patch releases.

The Single Source of Truth

Every versioned artifact in the text-to-cad ecosystem derives from plugins/cad/VERSION. This plain text file contains a strict SemVer string (e.g., 0.3.11) that serves as the definitive reference for npm packages, plugin metadata, and release tags.

The helper script scripts/release/sync-version.mjs runs during the build pipeline to propagate this canonical version to all dependent configuration files. Because downstream versions synchronize automatically from plugins/cad/VERSION, manual edits to package.json or other metadata files will be overwritten during the release process.

The bump-version.sh Script

The repository provides a dedicated bash utility at scripts/release/bump-version.sh to handle version increments safely. The script performs validation, calculation, file writes, and optional Git operations in a single atomic workflow.

SemVer Validation

Before any modification occurs, the script validates the current version string against SemVer specifications at lines 58–63. This prevents corrupted version strings from propagating into releases. You can optionally enforce an expected starting version using the --from-version flag to ensure you are bumping from the correct baseline.

Version Calculation Logic

The script calculates the next version based on the requested bump part at lines 73–89. It accepts three positional arguments for automatic incrementing:

• major – Increments the major version and resets minor/patch to zero
• minor – Increments the minor version and resets patch to zero
• patch – Increments the patch version (default behavior)

Alternatively, use --set-version to specify an explicit version string (useful for hotfixes or pre-releases).

How to Bump the Version

The script usage block at lines 24–31 outlines the standard workflow. Always run the script from the repository root.

Basic Patch Bump

Increment the patch version without creating a commit:

./scripts/release/bump-version.sh patch

Bump with Commit

Increment the minor version and automatically commit the change:

./scripts/release/bump-version.sh minor --commit

Full Release Workflow

Bump the major version, commit the change, and create a Git tag:

./scripts/release/bump-version.sh major --commit --tag

Advanced Options

Preview changes without modifying files using the dry-run mode:

./scripts/release/bump-version.sh patch --dry-run

Force-create or overwrite an existing tag with --force-tag, or specify an exact version:

./scripts/release/bump-version.sh --set-version 1.4.0 --commit --tag

What Happens After the Bump

Once the version file updates, the release pipeline takes over. The scripts/bundle/bundle.sh script triggers scripts/release/sync-version.mjs, which injects the new version into all package manifests and metadata files. Finally, scripts/release/create-github-release.sh generates the GitHub release using the version tag created during the bump.

This chain ensures that plugins/cad/VERSION remains the only manual touchpoint, while all derived artifacts stay synchronized automatically.

Summary

• plugins/cad/VERSION is the single source of truth for the text-to-cad version string.
• Use scripts/release/bump-version.sh exclusively to modify versions; never edit the VERSION file manually.
• The script validates SemVer compliance at lines 58–63 and calculates new versions at lines 73–89.
• Supported bump types are major, minor, patch, or explicit versions via --set-version.
• Flags like --commit, --tag, and --dry-run control Git operations and output preview.
• The sync script scripts/release/sync-version.mjs propagates the canonical version to all packages during the build process.

Frequently Asked Questions

Can I manually edit the VERSION file instead of using the script?

No. While plugins/cad/VERSION is a plain text file, manual edits bypass SemVer validation and Git tagging logic. The bump-version.sh script ensures that version increments follow semantic versioning rules and that Git history accurately reflects the change. Manual edits risk mismatched package versions downstream.

What if I need to release a specific version number rather than incrementing?

Use the --set-version flag followed by the exact SemVer string. For example: ./scripts/release/bump-version.sh --set-version 2.1.0 --commit --tag. This bypasses the automatic calculation logic while still validating the format and updating all metadata through the standard sync pipeline.

How do I verify what the script will do before making changes?

Run the command with the --dry-run flag. This mode executes the validation and calculation logic at lines 58–89 of bump-version.sh and prints the projected new version without writing to plugins/cad/VERSION or creating Git objects. Use this to preview major version jumps or verify --from-version constraints.

Why do I need to run scripts/release/sync-version.mjs separately?

You do not need to run it manually. According to the earthtojake/text-to-cad source code, sync-version.mjs executes automatically as part of the bundle script (scripts/bundle/bundle.sh) during the release pipeline. It reads plugins/cad/VERSION and injects that value into npm packages and plugin metadata, ensuring the canonical version propagates to all distribution artifacts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}