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

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 and 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 workflow validates that symlinks point to correct targets and that the bundle check passes.

Reference the symlink architecture in 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 (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 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:

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

Initialize the symlink layout required for editable development:

scripts/dev/setup-symlinks.sh

Verify the layout is correctly configured:

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 (lines 9-15).

Create a feature branch from the latest develop:

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
• JavaScript checks: scripts/test/test-js.sh
• Python checks: scripts/test/test-python.sh

Verify that generated outputs remain synchronized with the bundle script:

scripts/bundle/bundle.sh --check

Commit your changes and push the branch:

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:

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 workflow manually. Do not attempt to push release artifacts directly.

Dispatch the Release workflow from the develop branch:

gh workflow run Release --ref develop

The workflow performs the following atomic steps:

• Reads and increments the VERSION file.
• Executes 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.
• Use 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.
• Run tests via 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 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.

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 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 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.

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