Index: freecad-mcp-bridge follows its release branch

[zewpo]

Automated Index update from CREATeNG/freecad-mcp-bridge release v0.1.19.

• Entry: freecad-mcp-bridge
• Updates git_ref, branch_display_name, and zip_url

Repository: https://github.com/CREATeNG/freecad-mcp-bridge
Tag / git_ref: v0.1.19
Zip URL: https://github.com/CREATeNG/freecad-mcp-bridge/archive/refs/tags/v0.1.19.zip

Thanks for review.

[mnesarco]

FreeCAD Addon Development Workflow Guide

Core Recommendation Overview

Key Rule: Register a stable release branch in the FreeCAD Addon Index and do your day-to-day work in a separate development branch. When you want to push updates to users, merge the development branch into the release branch. You do not need to modify or re-submit to the index registry for routine updates.

---

1. The Problem Explained

When you submit an addon to the official FreeCAD Addon Index, your metadata entry points to a specific Git repository and branch (such as main or release).

If you do your daily development directly in that registered branch, there will be some problems:

• Users get unstable code: FreeCAD users who check for updates will receive experimental, incomplete, or broken code while you are actively working.
• Registry maintenance overhead: To avoid giving users broken code, you would have to update the index file with new commit hashes or tags manually via Pull Requests to the Addons repository for every update. NOT RECOMMENDED.

---

2. Recommended Branching Strategy

Maintain at least two distinct branches in your addon repository:

 (dev / feature)   ---> [ Draft Feature ] ---> [ Refactor ] ---> [ Bug Fix ]
                                                                     |
                                                                     | MERGE & PUSH
                                                                     v
 (release / main)  --------------------------------------------> [ Stable Release ]

Branch Roles

1. Development Branch (e.g., dev or development)

   • Purpose: Daily work, active feature development, experimentation, and debugging.
   • Visibility: Public on GitHub/GitLab, but ignored by the FreeCAD Addon Manager.

2. Release Branch (e.g., release or main)

   • Purpose: Holds only stable, fully tested code intended for end-users.
   • Visibility: Registered in the FreeCAD Addon Index registry.

---

3. Step-by-Step Workflow

Step 1: Initial Setup & Index Registration (One-Time)

1. Create a dev branch for active work and a release branch for stable releases.
2. Submit your Pull Request to the FreeCAD Addon Index pointing your entry's branch metadata to your release branch.

Step 2: Daily Development

1. Commit and push all day-to-day work to your dev branch.
2. Users opening FreeCAD's Addon Manager will not receive these updates yet, allowing you to break and fix things safely.

Step 3: Publishing an Update

1. Once your code is stable and ready for release, merge your dev branch into your release branch:

   git checkout release
   git merge dev
   git push origin release

2. Result: FreeCAD's Addon Manager automatically detects the new commits on the release branch and notifies users that an update is available. No pull request or index update is required!

---

4. Key Benefits

• Zero Index Maintenance: Register the addon URL and branch once; no repeated Pull Requests to the FreeCAD index repository.
• User Protection: End users are isolated from active development bugs.
• Clean History: You can squash or clean up commits in dev before merging into release.

[zewpo]

@chennes, cc @mnesarco — thanks for the guide. To check we've understood: our current workflow only opens an Index PR when we cut a release tag (the Addon Academy's "Alternative 1: tagged releases"). It never opens one for day-to-day pushes to main. In July you offered either tags or a release branch, so we went with tags.

If you'd rather we index a branch, we're happy to switch. We'd add a release branch that our release workflow moves to each verified release, set package.xml's repository branch to release, and stop opening Index PRs per release. This PR would then change our entry to git_ref: release instead of a tag.

@chennes, which do you prefer: keep tagged releases, or switch to a release branch?

[chennes]

It's your call, I'm happy to support either workflow. The workflow you've chosen was intended for slow-updating, stable addons, with infrequent changes. If that describes your addon, then you don't need to change anything.

[zewpo]

@chennes, thanks for the clear answer. We expect a settling-in period with fairly frequent releases, so we've switched to the branch workflow, as @mnesarco suggested.

This PR now points the entry at our release branch:

• git_ref and branch_display_name: release;
• zip_url: …/archive/refs/heads/release.zip.

Our release workflow only moves release forward, and only to a commit that has passed Addon Manager install verification on Linux, macOS and Windows. v0.1.20 is the first release shipped this way. This should be the last Index PR from us unless the branch name ever changes.