Purpose of the Develop and Main Branches in text-to-cad: A Complete Guide

The develop branch functions as the active development workspace featuring symlinked source directories for efficient editing, while main operates as a publish-only branch containing generated production outputs for end-user consumption.

The earthtojake/text-to-cad repository implements a dual-branch strategy to separate active development from production releases. Understanding the purpose of the develop and main branches is essential for contributors and users who need to know which branch to clone, modify, or deploy. This workflow ensures that developers can work with a flexible symlinked layout while end-users receive self-contained, ready-to-run code.

Develop Branch: Active Development and Symlinked Workflows

The develop branch serves as the primary integration branch where all contributors submit their work.

Symlink-Based Development Layout

Unlike the production branch, develop contains symlinks that map generated-output locations back to canonical source directories including skills/, viewer/, and packages/. This architectural choice allows developers to edit a single copy of shared code while the checkout layout appears as a complete production tree. The symlink configuration is managed by scripts/dev/setup-symlinks.sh, which creates and validates these links during local environment setup.

Contribution Workflow

All contributors must branch from develop and open pull requests back to it. According to CONTRIBUTING.md (lines 57-71), this branch receives all active development commits, while the CI Test workflow validates pull requests before integration. When working locally, developers should clone the repository using git clone --branch develop https://github.com/earthtojake/text-to-cad.git to ensure they have the correct symlinked layout.

Main Branch: Production and Publish-Only Releases

The main branch operates under strict constraints to guarantee stability for end-users.

Generated Production Outputs

The main branch contains generated production outputs with no symlinks, ensuring that a plain checkout runs without additional setup or repository-root modules on the import path. This self-contained structure allows end-users and CI pipelines to use the code immediately without executing build scripts or resolving symlink dependencies.

Release Workflow Automation

main never receives direct commits or pull requests. Instead, the official Release workflow (defined in .github/workflows/release.yml) automatically builds from develop, replaces symlinks with generated files, and pushes the resulting commit to main. This publish-only approach means validation occurs exclusively through the release pipeline rather than direct testing on main.

Working with the Branch Strategy

Setting Up Local Development

To begin development, clone the develop branch and verify the symlink layout:

# Clone the development branch

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

# Create and verify symlinks

git switch -c my-feature
scripts/dev/setup-symlinks.sh --check

Understanding Build Isolation

Despite the symlinked convenience in develop, the runtime self-containment rule requires that production builds run without any skills/ or repository-root modules on the import path. The release workflow enforces this by generating standalone outputs before pushing to main.

Summary

• Develop Branch: Active development workspace with symlinks to skills/, viewer/, and packages/; receives all pull requests and direct contributions.
• Main Branch: Publish-only branch containing generated production outputs; updated exclusively via the automated Release workflow.
• Key Script: scripts/dev/setup-symlinks.sh manages the development environment layout on develop.
• CI Strategy: Testing runs on develop pull requests, while main validation occurs only through the release pipeline.
• Source Documentation: Branch policies are detailed in CONTRIBUTING.md (lines 57-71) and AGENTS.md.

Frequently Asked Questions

How do I start contributing to the text-to-cad repository?

Clone the develop branch and create your feature branch from there. Run scripts/dev/setup-symlinks.sh to establish the symlinked development layout, then open pull requests back to develop rather than main.

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

The symlinks in develop point generated-output locations back to canonical source directories like skills/ and packages/, allowing developers to edit single copies of shared code while maintaining a full production tree appearance. This simplifies development but requires conversion to generated outputs before publishing.

Can I commit directly to the main branch?

No, main is strictly publish-only and never receives direct commits or pull requests. The branch updates exclusively through the Release workflow, which builds from develop and pushes generated outputs to main automatically.

What is the difference between the CI Test and Release workflows?

The Test workflow runs on pull requests to develop to validate changes before integration, while the Release workflow handles the transition from develop to main by building production outputs and enforcing runtime self-containment rules.

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