267 lines
14 KiB
Markdown
267 lines
14 KiB
Markdown
# Upstream Merge Plan: FreeCAD 1.0.0 → 1.2.0-dev
|
|
|
|
**Date:** February 2026
|
|
**Status:** Planning
|
|
|
|
## Overview
|
|
|
|
Kindred Create (`origin/main`) is based on FreeCAD 1.0.0 with ~193 Kindred-specific commits layered on top. The upstream fork (`upstream/main` at `github.com/Kindred-Systems/FreeCAD`) tracks FreeCAD development and is currently at **1.2.0-dev**. The two repositories diverged early and have ~45k commits each from a very old merge base — a traditional `git merge` is not feasible.
|
|
|
|
**Goal:** Forward-port all Kindred customizations onto the latest `upstream/main` (FreeCAD 1.2.0-dev) to pick up bug fixes and new features while preserving all Kindred functionality.
|
|
|
|
## Strategy: Diff-Based Forward Port
|
|
|
|
1. Create a new branch from `upstream/main`
|
|
2. Copy Kindred-only files/directories wholesale (no conflicts)
|
|
3. Cherry-pick or manually re-apply the ~36 C++ source patches
|
|
4. Build, test, and validate
|
|
|
|
---
|
|
|
|
## Remotes
|
|
|
|
| Remote | URL | Role |
|
|
|--------|-----|------|
|
|
| `origin` | `git.kindred-systems.com/kindred/create` | Kindred Create (current main) |
|
|
| `upstream` | `github.com/Kindred-Systems/FreeCAD` | FreeCAD fork tracking upstream development |
|
|
| `internal` | `gitea.kindred.internal:kindred/create-0070` | Internal mirror |
|
|
|
|
---
|
|
|
|
## Phase 1: Copy Kindred-Only Files (No Conflicts)
|
|
|
|
These files/directories exist only in Kindred Create and can be copied directly onto `upstream/main` without conflict.
|
|
|
|
### New directories (copy wholesale)
|
|
|
|
| Directory | Description |
|
|
|-----------|-------------|
|
|
| `kindred-icons/` | 1444 Catppuccin Mocha SVG icon overrides |
|
|
| `mods/silo/` | Silo workbench submodule (`silo-mod`) |
|
|
| `mods/ztools/` | ZTools workbench submodule |
|
|
| `src/Mod/Create/` | Kindred Create workbench (InitGui.py, kc_format.py, update_checker.py, version.py.in) |
|
|
| `package/` | rattler-build packaging recipe |
|
|
| `docs/` | Kindred documentation (architecture, specifications, guides) |
|
|
| `.gitea/` | CI workflows, issue templates, runner configs |
|
|
|
|
### New files in existing directories
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `src/Gui/FileOrigin.cpp/.h` | Origin abstraction layer |
|
|
| `src/Gui/FileOriginPython.cpp/.h` | Python bridge for origins |
|
|
| `src/Gui/OriginManager.cpp/.h` | Origin manager singleton |
|
|
| `src/Gui/OriginManagerDialog.cpp/.h` | Origin management dialog |
|
|
| `src/Gui/OriginSelectorWidget.cpp/.h` | Toolbar origin selector |
|
|
| `src/Gui/CommandOrigin.cpp` | PLM origin commands (Commit/Pull/Push/Info/BOM) |
|
|
| `src/Gui/BreadcrumbToolBar.cpp/.h` | Breadcrumb navigation bar |
|
|
| `src/Gui/EditingContext.cpp/.h` | Editing context system |
|
|
| `src/Gui/Icons/kindred-create.svg` | App icon |
|
|
| `src/Gui/Icons/kindredcreateabout.png` | About dialog image |
|
|
| `src/Gui/Icons/kindredcreatesplash*.png` | Splash screen images |
|
|
| `src/Gui/Icons/silo-*.svg` | Silo command icons (6 files) |
|
|
| `src/Gui/PreferencePacks/KindredCreate/` | Theme preference pack |
|
|
| `src/Gui/Stylesheets/KindredCreate.qss` | QSS stylesheet |
|
|
| `src/Gui/Stylesheets/parameters/KindredCreate.yaml` | Theme parameters |
|
|
| `src/Gui/Stylesheets/images_dark-light/branch_*_dark.svg` | Tree branch line SVGs (7 files) |
|
|
| `resources/kindred-create.*` | Platform file associations (ico, icns, xml, desktop) |
|
|
| `banner-logo-light.png` | Repository banner |
|
|
| `CONTRIBUTING.md` | Contribution guidelines |
|
|
|
|
---
|
|
|
|
## Phase 2: Cherry-Pick Core Changes (Conflict Risk)
|
|
|
|
36 Kindred commits touch core FreeCAD C++ files. Of those, **38 files** also changed on `upstream/main`, creating potential conflicts. Listed in chronological order (oldest first) for cherry-pick sequence.
|
|
|
|
### Commit sequence
|
|
|
|
| # | Hash | Summary | Conflict Risk | Files |
|
|
|---|------|---------|---------------|-------|
|
|
| 1 | `316d4f4b524` | Initial branding (CMakeLists, splash, about, theme, icons, QRC) | **HIGH** — CMakeLists.txt, DlgAbout.cpp, SplashScreen.cpp, resource.qrc all changed upstream | 14 files |
|
|
| 2 | `8c6837cc152` | Theme padding/clipping fixes | LOW — KindredCreate.qss is new file | 1 file |
|
|
| 3 | `bb3f3ac6d6c` | Dock task panel right, remove non-Kindred themes | **MEDIUM** — MainWindow.cpp, PreferencePacks CMakeLists changed upstream | 8 files |
|
|
| 4 | `e85162947b7` | Startup theme selector fix | **MEDIUM** — StartupProcess.cpp changed upstream | 4 files |
|
|
| 5 | `eb80c07f57a` | Theme QSS refinements | LOW — Kindred-only files | 4 files |
|
|
| 6 | `8639b6fd8ab` | Resolve unknown command/style token errors | **MEDIUM** — StartupProcess.cpp | 5 files |
|
|
| 7 | `fea1280fa90` | Theme alternate-background-color | LOW | 2 files |
|
|
| 8 | `b3fedfb19fb` | Theme tree item padding | LOW | 2 files |
|
|
| 9 | `0d4545b7d67` | Tree branch line SVGs | LOW — new files | 8 files |
|
|
| 10 | `434ae797a43` | Theme selector cleanup | **MEDIUM** — StartupProcess.cpp | 4 files |
|
|
| 11 | `224feda4ad6` | Catppuccin icon override infrastructure | **MEDIUM** — BitmapFactory.cpp, CMakeLists.txt | 2 files |
|
|
| 12 | `7535a48ec4c` | Origin abstraction layer | **HIGH** — Application.cpp, ApplicationPy.cpp/.h, CMakeLists.txt | 6 files (4 new) |
|
|
| 13 | `38358e431d2` | LocalFileOrigin and Std_* delegation | **HIGH** — CommandDoc.cpp, FileOrigin.cpp/.h | 3 files |
|
|
| 14 | `79c85ed2e5d` | FileOriginPython interactive methods | LOW — Kindred-only files | 3 files |
|
|
| 15 | `deeb6376f71` | OriginSelectorWidget | **HIGH** — Action.cpp/.h, CommandStd.cpp, Workbench.cpp, CMakeLists.txt | 8 files |
|
|
| 16 | `679aaec6d49` | Origin commands (Commit/Pull/Push) | **MEDIUM** — Application.cpp, Command.h, Workbench.cpp | 5 files |
|
|
| 17 | `db85277f262` | OriginManagerDialog | LOW — new files + OriginSelectorWidget.cpp | 3 files |
|
|
| 18 | `015df38328c` | Document-origin tracking in window title | **MEDIUM** — MDIView.cpp | 3 files |
|
|
| 19 | `a6e84552da5` | Cross-origin detection in SaveAs | **MEDIUM** — CommandDoc.cpp | 1 file |
|
|
| 20 | `84b69b935b2` | Build fix: remove SelectModule.h include | LOW | 1 file |
|
|
| 21 | `2f594dac0a5` | Use Python API for viewDefaultOrientation | **MEDIUM** — CommandDoc.cpp | 1 file |
|
|
| 22 | `724440dcb75` | Build fixes for OriginSelectorWidget/Manager | LOW — Kindred files | 2 files |
|
|
| 23 | `c858706d480` | Add silo icons to QRC | LOW — resource.qrc (additive) | 6 files |
|
|
| 24 | `d95c850b7b1` | Widen origin selector widget | LOW | 1 file |
|
|
| 25 | `10b5c9d584f` | Wire OriginManagerDialog to Silo_Settings | LOW | 1 file |
|
|
| 26 | `cc5ba638d1f` | UI polish — Wayland scaling, menu icon size | **HIGH** — DlgSettingsGeneral.cpp/.h/.ui changed upstream | 6 files |
|
|
| 27 | `4bf74cf3391` | Build fix for DlgSettingsGeneral | **MEDIUM** — DlgSettingsGeneral.h, StartupProcess.cpp | 2 files |
|
|
| 28 | `6773ca0dfd8` | Eliminate QSS/CFG duplication | LOW — Kindred files | 3 files |
|
|
| 29 | `977fa3c9347` | QGroupBox indicator, hyperlink color | LOW — KindredCreate.qss | 1 file |
|
|
| 30 | `8b2ce4b73a4` | Native Qt start panel + kindred:// URL | **MEDIUM** — MainWindow.cpp | 1 file |
|
|
| 31 | `bf637af4e45` | Window flickering and icon clipping fix | **MEDIUM** — MainWindow.cpp/.h | 3 files |
|
|
| 32 | `70118201b02` | MDI pre-document tab for Silo new item | **HIGH** — ApplicationPy, BreadcrumbToolBar, EditingContext, MainWindow, Workbench | 11 files |
|
|
| 33 | `1f49e3fa6da` | Build fix: ToolBarItem incomplete type, reportException | **LOW** — likely already fixed upstream | 2 files |
|
|
| 34 | `f71decca089` | Splash screen: skip runtime draw, mantle bg | **MEDIUM** — SplashScreen.cpp | 3 files |
|
|
| 35 | `2b0c6774c07` | Dev build defaults, skip version migration | **MEDIUM** — CMakeLists.txt, DlgVersionMigrator.cpp | 2 files |
|
|
| 36 | `ab71902a4c2` | Forward visibility arg in appendToolbar() | LOW — FreeCADGuiInit.py | 1 file |
|
|
|
|
### HIGH conflict files (need manual attention)
|
|
|
|
These files are modified by both Kindred and upstream. They will almost certainly require manual conflict resolution:
|
|
|
|
| File | Kindred Changes | Upstream Risk |
|
|
|------|----------------|---------------|
|
|
| `CMakeLists.txt` | Kindred version vars, build config | Upstream version bumps, new modules |
|
|
| `src/Gui/Application.cpp` | Origin system registration | Core refactoring |
|
|
| `src/Gui/ApplicationPy.cpp/.h` | `addFileOrigin()`, MDI tab API | API changes |
|
|
| `src/Gui/CommandDoc.cpp` | Origin delegation, cross-origin SaveAs, viewDefaultOrientation | Save/open refactoring |
|
|
| `src/Gui/Action.cpp/.h` | OriginSelectorWidget toolbar action | Toolbar system changes |
|
|
| `src/Gui/MainWindow.cpp/.h` | Task panel docking, start panel, flicker fix | UI restructuring |
|
|
| `src/Gui/Workbench.cpp/.h` | Origin selector, toolbar visibility, ToolBarItem include | Workbench changes |
|
|
| `src/Gui/SplashScreen.cpp` | Kindred branding, skip runtime draw | Splash updates |
|
|
| `src/Gui/StartupProcess.cpp/.h` | Theme selector, menu icon size | Startup flow changes |
|
|
| `src/Gui/CMakeLists.txt` | New source files (Origin*, BreadcrumbToolBar, EditingContext) | New upstream sources |
|
|
| `src/Gui/DlgSettingsGeneral.cpp/.h/.ui` | Menu icon size preference | Settings UI changes |
|
|
|
|
---
|
|
|
|
## Phase 3: Module-Level Changes
|
|
|
|
### Assembly fixes (check if still needed)
|
|
|
|
| Hash | Summary | Status |
|
|
|------|---------|--------|
|
|
| `316d4f4b524` | Joint flip overconstrain fix | May be fixed upstream — verify |
|
|
| `9dc50cef727` | SIGSEGV during document restore | May be fixed upstream — verify |
|
|
| `ddefb236521` | Solver ignoring datum plane refs | May be fixed upstream — verify |
|
|
| `b7374d7b1fc` | findPlacement() datum/origin handling | May be fixed upstream — verify |
|
|
|
|
Files touched: `src/Mod/Assembly/App/AssemblyObject.cpp`, `src/Mod/Assembly/UtilsAssembly.py`, `src/Mod/Assembly/InitGui.py`
|
|
|
|
### FreeCADInit.py
|
|
|
|
| Hash | Summary |
|
|
|------|---------|
|
|
| (Layer 1 `.kc`) | `addImportType` includes `*.kc` |
|
|
|
|
### FreeCADGuiInit.py
|
|
|
|
| Hash | Summary |
|
|
|------|---------|
|
|
| `ab71902a4c2` | Forward visibility arg in `appendToolbar()` |
|
|
|
|
---
|
|
|
|
## Phase 4: Build System and Packaging
|
|
|
|
| Item | Action |
|
|
|------|--------|
|
|
| `CMakeLists.txt` | Re-apply Kindred version variables on top of upstream 1.2.0-dev |
|
|
| `package/rattler-build/recipe.yaml` | Update for new version, verify dependency pins |
|
|
| `.gitea/workflows/` | Verify CI still works with updated source |
|
|
| Submodule pins | Re-add `mods/silo`, `mods/ztools` submodules |
|
|
| `src/3rdParty/OndselSolver` | Verify our fork is still needed or if upstream fixed the issues |
|
|
|
|
---
|
|
|
|
## Phase 5: Validation
|
|
|
|
1. **Build**: Full CMake configure + build succeeds
|
|
2. **Launch**: Application starts without errors, splash and about dialogs show Kindred branding
|
|
3. **Theme**: KindredCreate theme loads correctly, QSS applies
|
|
4. **Icons**: kindred-icons override system works (BitmapFactory loads from kindred-icons/)
|
|
5. **Origin system**: FileOrigin, OriginManager, OriginSelectorWidget functional
|
|
6. **Silo integration**: Auth panel, activity panel, save/commit/pull all work
|
|
7. **File format**: `.kc` files open/save with silo/ directory preserved
|
|
8. **Assembly**: Verify assembly fixes aren't regressed (or confirm upstream fixed them)
|
|
9. **Start panel**: Native Qt start panel loads
|
|
10. **URL scheme**: `kindred://` URL handling works
|
|
|
|
---
|
|
|
|
## Execution Steps
|
|
|
|
```bash
|
|
# 1. Ensure upstream is fetched
|
|
git fetch upstream
|
|
|
|
# 2. Create forward-port branch from upstream/main
|
|
git checkout -b kindred-on-upstream-1.2 upstream/main
|
|
|
|
# 3. Copy Kindred-only directories
|
|
git checkout origin/main -- kindred-icons/ mods/ src/Mod/Create/ package/ docs/ \
|
|
.gitea/ resources/kindred* banner-logo-light.png CONTRIBUTING.md .gitmodules
|
|
|
|
# 4. Copy new Kindred source files (no conflicts)
|
|
git checkout origin/main -- \
|
|
src/Gui/FileOrigin.cpp src/Gui/FileOrigin.h \
|
|
src/Gui/FileOriginPython.cpp src/Gui/FileOriginPython.h \
|
|
src/Gui/OriginManager.cpp src/Gui/OriginManager.h \
|
|
src/Gui/OriginManagerDialog.cpp src/Gui/OriginManagerDialog.h \
|
|
src/Gui/OriginSelectorWidget.cpp src/Gui/OriginSelectorWidget.h \
|
|
src/Gui/CommandOrigin.cpp \
|
|
src/Gui/BreadcrumbToolBar.cpp src/Gui/BreadcrumbToolBar.h \
|
|
src/Gui/EditingContext.cpp src/Gui/EditingContext.h \
|
|
src/Gui/Icons/kindred-create.svg src/Gui/Icons/kindredcreateabout.png \
|
|
src/Gui/Icons/kindredcreatesplash.png src/Gui/Icons/kindredcreatesplash_2x.png \
|
|
src/Gui/Icons/silo-bom.svg src/Gui/Icons/silo-commit.svg \
|
|
src/Gui/Icons/silo-info.svg src/Gui/Icons/silo-pull.svg \
|
|
src/Gui/Icons/silo-push.svg \
|
|
src/Gui/PreferencePacks/KindredCreate/ \
|
|
src/Gui/Stylesheets/KindredCreate.qss \
|
|
src/Gui/Stylesheets/parameters/KindredCreate.yaml \
|
|
src/Gui/Stylesheets/images_dark-light/
|
|
|
|
# 5. Cherry-pick core changes (oldest to newest)
|
|
# Resolve conflicts as they arise
|
|
git cherry-pick 316d4f4b524 # Initial branding
|
|
git cherry-pick 8c6837cc152 # Theme padding
|
|
# ... (continue through all 36 commits)
|
|
git cherry-pick ab71902a4c2 # appendToolbar visibility
|
|
|
|
# 6. Apply .kc format Layer 1 changes
|
|
# (These were written against 1.0.0, re-apply on 1.2.0-dev)
|
|
|
|
# 7. Build and test
|
|
cmake -B build -S . && cmake --build build
|
|
|
|
# 8. Push and create PR
|
|
git push -u origin kindred-on-upstream-1.2
|
|
```
|
|
|
|
---
|
|
|
|
## Risk Mitigation
|
|
|
|
- **Checkpoint after each cherry-pick**: Commit progress so partial work isn't lost
|
|
- **Build after each batch**: Group related commits (e.g., all theme commits) and build after each group
|
|
- **Skip already-fixed commits**: Some bug fixes (Assembly, build errors) may already be resolved upstream — check before cherry-picking
|
|
- **Test incrementally**: Don't wait until all 36 commits are applied to test
|
|
|
|
## Estimated Effort
|
|
|
|
| Phase | Effort |
|
|
|-------|--------|
|
|
| Phase 1 (copy wholesale) | ~30 min |
|
|
| Phase 2 (cherry-pick 36 commits) | ~4-8 hours (conflict resolution) |
|
|
| Phase 3 (module changes) | ~1 hour |
|
|
| Phase 4 (build system) | ~1-2 hours |
|
|
| Phase 5 (validation) | ~2-3 hours |
|
|
|
|
## Future: Staying in Sync
|
|
|
|
After this merge, establish a recurring upstream sync process:
|
|
1. Track `upstream/main` with periodic merges (weekly or per-release)
|
|
2. Keep Kindred changes as isolated as possible (separate files > modifying upstream files)
|
|
3. Consider upstreaming non-Kindred-specific fixes to the FreeCAD fork
|