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

> Learn how to update text-to-cad by cloning the develop branch, creating a feature branch, editing source files, testing, and submitting a pull request. Follow our release workflow.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-07-24

---

**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:

```bash
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:

```bash
git switch -c my-feature

```

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

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```python

# 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:

```bash
./.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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py) contains the core Python API used by many skills for STEP generation.

To add a new helper function:

```python

# 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`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/__init__.py):

```python
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):

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

```

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

```bash
npm --prefix viewer run test

```

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

```bash
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:

```bash
scripts/bundle/bundle.sh --clean

```

Verify bundle freshness:

```bash
scripts/bundle/bundle.sh --check

```

This process is documented in the "Generated runtime and plugin freshness" section of [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md).

## Submitting Changes and Releasing

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

```bash
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:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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`.