How to Update text-to-cad: Complete Development and Release Workflow

To update text-to-cad, clone the develop branch, create a feature branch, edit canonical source files in packages/ or skills/, run targeted tests, and open a pull request targeting develop; releases are generated via GitHub workflow.

Updating the earthtojake/text-to-cad repository requires following a strict two-branch workflow that separates active development from production releases. This guide explains how to properly update text-to-cad by editing canonical source files, validating changes through the repository's test matrix, and optionally triggering automated releases.

Setting Up the Development Environment

All updates to text-to-cad start on the develop branch, which contains the editable source and symlink layout used for local development.

Clone the repository and switch to the develop branch:

git clone --branch develop https://github.com/earthtojake/text-to-cad.git
cd text-to-cad

Create a short-lived feature branch for your work:

git switch -c my-feature

Install the Python and Node dependencies that power the skills and the CAD Viewer:

python3.12 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements-dev.txt
npm --prefix viewer install

These steps are documented in the repository's CONTRIBUTING.md.

Understanding the Repository Structure

The text-to-cad project uses a symlink layout that distinguishes between canonical source files and generated output. The develop branch contains the editable source, while the main branch contains production-ready bundles.

Key directories:

• packages/ – Shared runtime helpers (e.g., packages/cadpy/)
• skills/ – Individual skill logic (e.g., skills/cad/, skills/urdf/)
• references/ – Reference documentation
• plugins/ – Generated output (symlinks to skills/)

When you modify a file, edit the canonical source under packages/ or skills/. The symlink in plugins/cad/skills/ automatically reflects the change. This rule is enforced by the repository layout described in AGENTS.md.

Making Changes to Source Code

Updating CAD Skills

Skill logic lives in skills/<skill>/scripts/. For example, the CAD skill’s CLI entry point is located at skills/cad/scripts/step.

To add a new command-line flag to the CAD skill:

# skills/cad/scripts/step.py (excerpt)

parser.add_argument(
    "--tolerance",
    type=float,
    default=0.01,
    help="Geometric tolerance in mm for validation checks",
)

After editing, verify the CLI loads correctly:

./.venv/bin/python skills/cad/scripts/step.py --help

Modifying Shared Packages

Shared runtime helpers live in packages/cadpy/. For example, packages/cadpy/src/cadpy/api.py contains the core Python API used by many skills for STEP generation.

To add a new helper function:

# packages/cadpy/src/cadpy/new_helper.py

def compute_center_of_mass(step_file: str) -> tuple[float, float, float]:
    """Return the (x, y, z) centre of mass of the given STEP file."""
    # implementation uses cadpy.step_scene parsing …

    pass

Export the module in packages/cadpy/src/cadpy/__init__.py:

from .new_helper import compute_center_of_mass

Testing Your Updates

Before committing, verify that your change passes the smallest applicable test suite.

Python skill tests (e.g., for the URDF skill):

./.venv/bin/python -m unittest tests/python/skills/urdf/test_cli.py

JavaScript package tests (e.g., for the CAD Viewer):

npm --prefix viewer run test

Repository-wide validation (runs all checks on the symlink layout):

scripts/test/test.sh

If any test fails, locate the failing file in the output and fix the underlying bug before pushing.

Bundling and Validation

After changing shared code, rebuild the production-ready bundles to ensure the main branch can be generated from a clean state.

Run the bundle script with the clean flag:

scripts/bundle/bundle.sh --clean

Verify bundle freshness:

scripts/bundle/bundle.sh --check

This process is documented in the "Generated runtime and plugin freshness" section of AGENTS.md.

Submitting Changes and Releasing

Stage only the files you edited in the canonical source. Never commit generated output.

git add <modified files>
git commit -m "Brief description of the change"
git push -u origin my-feature

Open a pull request targeting the develop branch. CI will run the full test matrix, including bundling and documentation checks.

Once the PR passes CI and is approved, merge it into develop.

To create a new release, trigger the repository’s Release workflow:

gh workflow run release.yml --ref develop -f bump=patch

The workflow automatically bumps plugins/cad/VERSION, rebuilds production bundles, creates a GitHub Release, and publishes the new artifacts to main.

Summary

• Clone the develop branch to access editable source and symlinks.
• Edit canonical files in packages/ or skills/; never edit generated output directly.
• Run targeted tests using unittest for Python or npm test for JavaScript before committing.
• Bundle changes with scripts/bundle/bundle.sh --clean when modifying shared packages.
• Target develop for pull requests; use the Release workflow to publish to main.

Frequently Asked Questions

Which branch should I target when updating text-to-cad?

Always target the develop branch for pull requests. The develop branch contains the editable source files and symlink layout, while main contains generated production bundles that are updated automatically by the Release workflow.

How do I test changes to a specific skill?

Run the unit test file corresponding to that skill. For example, test the URDF skill CLI with ./.venv/bin/python -m unittest tests/python/skills/urdf/test_cli.py. For JavaScript components, use npm --prefix viewer run test.

What is the difference between the develop and main branches?

The develop branch holds the canonical source code, symlinks, and development environment configuration. The main branch holds frozen, production-ready bundles generated by scripts/bundle/bundle.sh and is updated only through automated releases.

How do I create a new release after merging changes?

After merging to develop, run gh workflow run release.yml --ref develop -f bump=patch (or minor/major). This triggers the Release workflow, which updates plugins/cad/VERSION, rebuilds bundles, creates a GitHub Release, and pushes the artifacts to main.

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