# How the Develop Branch Powers Active Development in text-to-cad > Discover how the develop branch in earthtojake/text-to-cad drives active development. Learn about rapid iteration and symlink layouts while the main branch stays pristine. Get the details. - Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad) - Tags: how-to-guide - Published: 2026-07-31 --- **The `develop` branch serves as the active development workspace for the `earthtojake/text-to-cad` repository, utilizing a symlink-driven layout to enable rapid iteration while the `main` branch remains a pristine, publish-only snapshot.** The `develop` branch functions as the **engine room** for the text-to-cad workbench, hosting all day-to-day changes, new skills, bug fixes, and experiments. Unlike the `main` branch, which contains only self-contained, installable releases, `develop` employs a sophisticated symlink architecture that links generated output paths back to canonical source directories. This design allows developers to edit a single source file and have changes instantly reflected across all dependent locations. ## The Develop Branch vs. Main: A Dual-Branch Strategy The repository maintains a strict separation between development and production code. The `develop` branch contains **symlinks** that point runtime builds, plugin copies, and viewer assets back to canonical source directories such as `skills/`, `viewer/`, and `packages/`. This allows for live, mutable development where changes propagate immediately. In contrast, the `main` branch contains **real generated files** with no symlinks and is designated as **publish-only**. According to [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), no direct pushes or pull requests to `main` are permitted, ensuring that anyone checking out `main` receives a fully self-contained, reproducible release. ## Understanding the Symlink-Driven Layout ### Canonical Sources and Generated Outputs The symlink architecture requires developers to edit the **target of the symlink**, not the link itself. When you modify a file under [`packages/cadpy/src/cadpy/helpers.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/helpers.py), the change instantly appears in dependent locations like `skills/your-skill/` or `plugins/cad/` because they resolve to the same physical file on disk. This prevents divergent copies and maintains a single source of truth across the repository. As documented in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) (lines 77-78), you must always "edit the source reached by the `develop` symlink layout first" rather than modifying files within symlinked paths directly. ### The setup-symlinks.sh Script The [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) utility creates and validates the symlink tree required for development. Run this script after cloning the `develop` branch or whenever structural changes occur. ```bash # Clone the repository and check out the develop branch git clone --branch develop https://github.com/earthtojake/text-to-cad.git cd text-to-cad # Create the symlink layout scripts/dev/setup-symlinks.sh # Verify symlinks are correctly configured scripts/dev/setup-symlinks.sh --check ``` ## Development Workflow Rules All feature work must follow the **branch-first rule**: always start a feature branch from `develop` and open pull requests back to `develop`. This guarantees that the symlinked layout used for development is preserved and that CI runs against the correct branch. ```bash # Create a feature branch off develop git switch -c my-new-skill # Edit canonical source files (not symlinks) nano packages/cadpy/src/cadpy/helpers.py # Stage and commit changes git add . git commit -m "Add new CAD helper utilities" # Push and open PR back to develop git push -u origin my-new-skill ``` As noted in [`CONTRIBUTING.md`](https://github.com/earthtojake/text-to-cad/blob/main/CONTRIBUTING.md) (lines 65-73), this workflow ensures that the development environment remains consistent across all contributors' machines. ## Continuous Integration on Develop The CI pipeline runs exclusively against the `develop` branch to validate the symlink layout before testing. According to [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md) (lines 38-46), the test workflow performs the following sequence: 1. Verifies the symlink layout integrity 2. Bundles generated outputs 3. Executes unit and integration tests This ensures that any change on `develop` still produces a valid production bundle suitable for merging into `main`. ```bash # Run the full test suite locally (includes symlink validation) scripts/test/test.sh ``` ## Summary - The `develop` branch acts as a **live workspace** with symlink-driven file resolution, while `main` remains a frozen, publish-only release. - **Symlinks** in `develop` point generated outputs back to canonical sources in `packages/`, `skills/`, and `viewer/` directories. - Always edit the **canonical source files** rather than files within symlinked paths to prevent code divergence. - Use [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) to initialize or validate the development environment after cloning. - All pull requests must target `develop`, never `main`, ensuring CI validates the symlink layout before release. ## Frequently Asked Questions ### How do I switch from working on main to develop? Checkout the `develop` branch and run the setup script to initialize symlinks. Unlike `main`, which contains static generated files, `develop` requires the symlink layout to function correctly. Execute [`scripts/dev/setup-symlinks.sh`](https://github.com/earthtojake/text-to-cad/blob/main/scripts/dev/setup-symlinks.sh) immediately after switching branches to ensure all paths resolve properly. ### What happens if I edit a file inside a symlinked directory? Editing files within symlinked paths creates divergent copies that break the single source of truth. According to the repository rules in [`AGENTS.md`](https://github.com/earthtojake/text-to-cad/blob/main/AGENTS.md), you must navigate to the **canonical source** (typically under `packages/` or `skills/`) and edit the target file directly. Changes then propagate automatically to all symlinked locations. ### Why can't I push directly to main? The `main` branch is **publish-only** and protected to guarantee that every commit represents a fully self-contained, installable release. All development work flows through `develop` where CI validates symlink integrity and generated bundles. This separation prevents unstable code from reaching production releases. ### How does the CI system validate develop branch changes? The CI workflow defined in the test scripts first verifies that the symlink layout matches the expected structure, then bundles all generated outputs, and finally runs the complete test suite. This three-stage validation ensures that code merged into `develop` can successfully generate the static files required for `main`.