# Git Workflow for Developing on develop vs main Release Branches in text-to-cad

> Master the Git workflow for text-to-cad development. Learn to use develop and main branches effectively for seamless releases and read-only production channels.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: best-practices
- Published: 2026-08-04

---

**Work exclusively on the `develop` branch using symlinks for editable source code, while treating `main` as a read-only, production-ready release channel populated only by the automated Release workflow.**

The **text-to-cad** repository maintains a strict dual-branch strategy that separates active development from distribution. According to the project's [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) and [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), contributors must branch from `develop`, maintain a symlinked local layout, and never push directly to `main`.

## The Dual-Branch Model

Understanding the distinction between these two branches prevents broken builds and ensures generated assets stay synchronized.

### The develop Branch (Active Development)

The `develop` branch contains the canonical source code and uses a **symlinked layout** to replicate generated outputs back to their source locations. This allows for a fast feedback loop where changes to source files immediately reflect in generated bundles without manual copying.

Key characteristics:
- **Editable source**: Skills, packages, and tests are modified directly here.
- **Symlink replication**: Generated files are symlinked rather than materialized, keeping the repository clean for development.
- **CI validation**: The [`test.yml`](https://github.com/earthtojake/text-to-cad/blob/main/test.yml) workflow validates that symlinks point to correct targets and that the bundle check passes.

Reference the symlink architecture in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) (lines 65-71) for details on how generated paths map back to canonical sources.

### The main Branch (Production Releases)

The `main` branch is **publish-only** and strictly protected. It contains fully materialized (non-symlinked) generated files that enable agents to install the plugin without build steps.

As documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) (lines 13-21), direct commits to `main` are prohibited. All changes arrive via the automated Release workflow, which:
1. Checks out `develop`.
2. Bumps the version in the `VERSION` file.
3. Executes [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) to materialize production outputs.
4. Commits the resulting artifacts to `main`.
5. Publishes a GitHub Release.

## Setting Up the Development Environment

Start every contribution by cloning the `develop` branch and initializing the symlink layout.

Clone the repository with the correct branch:

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

```

Initialize the symlink layout required for editable development:

```bash
scripts/dev/setup-symlinks.sh

```

Verify the layout is correctly configured:

```bash
scripts/dev/setup-symlinks.sh --check

```

This script creates the mapping between source directories and generated output locations, ensuring that tools can resolve paths correctly during local development.

## Contributing Code to the develop Branch

Follow the feature-branch workflow defined in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) (lines 9-15).

Create a feature branch from the latest `develop`:

```bash
git switch -c my-feature

```

Make your changes to skills, tests, or package configurations. Run the appropriate validation suites:

- **Full test suite**: [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh)
- **JavaScript checks**: [`scripts/test/test-js.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test-js.sh)
- **Python checks**: [`scripts/test/test-python.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test-python.sh)

Verify that generated outputs remain synchronized with the bundle script:

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

```

Commit your changes and push the branch:

```bash
git add .
git commit -m "feat: describe the change"
git push -u origin my-feature

```

Open a Pull Request targeting `develop` using the GitHub CLI:

```bash
gh pr create --base develop --head my-feature --title "Add feature" --body "Description"

```

CI will validate the symlink layout, run the test suite, and ensure generated outputs are up-to-date before allowing merge.

## Releasing to the main Branch

When maintainers are ready to cut a release, they trigger the [`.github/workflows/release.yml`](https://github.com/earthtojake/text-to-cad/blob/main/.github/workflows/release.yml) workflow manually. Do not attempt to push release artifacts directly.

Dispatch the Release workflow from the `develop` branch:

```bash
gh workflow run Release --ref develop

```

The workflow performs the following atomic steps:
- Reads and increments the `VERSION` file.
- Executes [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) to generate production-ready outputs (no symlinks).
- Commits the materialized bundle to `main`.
- Creates a GitHub Release with the new version tag.

This ensures that `main` always represents a complete, self-contained distribution that agents can consume without external build dependencies.

## Summary

- **Branch from `develop`** for all new features and bug fixes, as specified in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md).
- **Use [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh)** to establish the editable development layout required for the `develop` branch.
- **Never commit to `main`** directly; this branch is strictly publish-only per [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md).
- **Run tests** via [`scripts/test/test.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/test/test.sh) and verify bundles with `scripts/bundle/bundle.sh --check` before submitting PRs.
- **Trigger releases** using the GitHub Release workflow, which automatically materializes production files from `develop` onto `main`.

## Frequently Asked Questions

### What happens if I accidentally commit to main instead of develop?

Direct commits to `main` violate the repository policy outlined in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) and will likely be rejected by branch protection rules. If you accidentally push to `main`, revert the commit immediately and move your changes to a feature branch based off `develop`. The `main` branch should only receive updates through the automated Release workflow that runs [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh).

### Why does the develop branch use symlinks instead of generated files?

The symlink layout on `develop` allows developers to edit source files once while changes propagate automatically to dependent generated paths. This avoids the complexity of manually synchronizing generated outputs during active development. The [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) script creates these mappings, and CI validates them to ensure the layout matches the expected structure before any merge.

### How do I update the version number for a new release?

Do not manually edit the `VERSION` file on `main` or `develop` if you are a standard contributor. Maintainers trigger the Release workflow via `gh workflow run Release --ref develop`, which automatically bumps the version, runs [`scripts/bundle/bundle.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/bundle/bundle.sh) to materialize outputs, and commits everything to `main`. This ensures the version stamp and bundled artifacts remain perfectly synchronized.

### Can I run the release bundle script locally to test production output?

Yes. Run `scripts/bundle/bundle.sh --check` from your feature branch to verify that your changes generate valid production outputs without actually committing them. This simulates what the Release workflow does when building for `main`, helping you catch generation errors before opening your pull request to `develop`.