docs: write CREATE_MODULE.md — bootstrap module, update checker, and version management #93

New Issue

forbes · 2026-02-09T13:45:23Z

forbes commented

2026-02-09 13:45:23 +00:00

Tier 2 — Component Guide

File: docs/CREATE_MODULE.md

What this document should cover

Purpose — src/Mod/Create/ is the Kindred bootstrap module. It contains no feature code — its sole job is to wire ztools and Silo into FreeCAD at startup and manage versioning.
File inventory (small module — document every file):
- Init.py — console-phase bootstrap
  - setup_kindred_addons() — adds mods/ztools/ztools and mods/silo/freecad to sys.path
  - Executes each addon's Init.py, logs success/failure
- InitGui.py — GUI-phase bootstrap
  - setup_kindred_workbenches() — runs addon InitGui.py files to register workbenches
  - Deferred QTimer cascade with specific timings:
    - 1500ms: _register_silo_origin() — Silo becomes available in origin selector
    - 2000ms: _setup_silo_auth_panel() — Database Auth dock widget
    - 3000ms: _check_silo_first_start() — Settings prompt on first use
    - 4000ms: _setup_silo_activity_panel() — Database Activity dock widget (SSE)
    - 10000ms: _check_for_updates() — Gitea API version check
- update_checker.py — checks Gitea releases API for newer versions
- version.py.in — CMake template; configure_file() injects version at build time
- CMakeLists.txt — build rules, install targets
Version management:
- version.py.in template variables
- CMake version constants: KINDRED_CREATE_VERSION, FREECAD_VERSION
- How version flows from CMakeLists.txt → version.py → update checker → UI
Update checker details:
- API endpoint (Gitea releases)
- Version comparison logic
- User notification mechanism
- How to configure/disable
Why the QTimer cascade exists — FreeCAD's startup is not fully synchronous; Silo registration must wait for GUI framework readiness. Explain the ordering constraints.

Key source files

src/Mod/Create/Init.py
src/Mod/Create/InitGui.py
src/Mod/Create/update_checker.py
src/Mod/Create/version.py.in
src/Mod/Create/CMakeLists.txt
CMakeLists.txt (root) — version constants

Acceptance criteria

Every file in src/Mod/Create/ is documented
QTimer cascade is explained with timing rationale
Version injection pipeline is traced end-to-end
Update checker behavior is documented

## Tier 2 — Component Guide **File:** `docs/CREATE_MODULE.md` ### What this document should cover 1. **Purpose** — `src/Mod/Create/` is the Kindred bootstrap module. It contains no feature code — its sole job is to wire ztools and Silo into FreeCAD at startup and manage versioning. 2. **File inventory** (small module — document every file): - `Init.py` — console-phase bootstrap - `setup_kindred_addons()` — adds `mods/ztools/ztools` and `mods/silo/freecad` to `sys.path` - Executes each addon's `Init.py`, logs success/failure - `InitGui.py` — GUI-phase bootstrap - `setup_kindred_workbenches()` — runs addon `InitGui.py` files to register workbenches - Deferred QTimer cascade with specific timings: - 1500ms: `_register_silo_origin()` — Silo becomes available in origin selector - 2000ms: `_setup_silo_auth_panel()` — Database Auth dock widget - 3000ms: `_check_silo_first_start()` — Settings prompt on first use - 4000ms: `_setup_silo_activity_panel()` — Database Activity dock widget (SSE) - 10000ms: `_check_for_updates()` — Gitea API version check - `update_checker.py` — checks Gitea releases API for newer versions - `version.py.in` — CMake template; `configure_file()` injects version at build time - `CMakeLists.txt` — build rules, install targets 3. **Version management:** - `version.py.in` template variables - CMake version constants: `KINDRED_CREATE_VERSION`, `FREECAD_VERSION` - How version flows from `CMakeLists.txt` → `version.py` → update checker → UI 4. **Update checker details:** - API endpoint (Gitea releases) - Version comparison logic - User notification mechanism - How to configure/disable 5. **Why the QTimer cascade exists** — FreeCAD's startup is not fully synchronous; Silo registration must wait for GUI framework readiness. Explain the ordering constraints. ### Key source files - `src/Mod/Create/Init.py` - `src/Mod/Create/InitGui.py` - `src/Mod/Create/update_checker.py` - `src/Mod/Create/version.py.in` - `src/Mod/Create/CMakeLists.txt` - `CMakeLists.txt` (root) — version constants ### Acceptance criteria - [ ] Every file in `src/Mod/Create/` is documented - [ ] QTimer cascade is explained with timing rationale - [ ] Version injection pipeline is traced end-to-end - [ ] Update checker behavior is documented

forbes added the documentation label 2026-02-09 13:45:23 +00:00

forbes commented

2026-02-09 14:13:49 +00:00

Superseded by the mdBook documentation structure set up in PR #105. The content scope of this issue is now covered by the pages in docs/src/. Remaining content work is tracked in #104.

Superseded by the mdBook documentation structure set up in PR #105. The content scope of this issue is now covered by the pages in `docs/src/`. Remaining content work is tracked in #104.

forbes closed this issue

2026-02-09 14:13:49 +00:00

forbes referenced this issue from a commit

2026-02-14 16:31:27 +00:00

Merge pull request #93 from ianrrees/20160213-fix-non-gui-build

forbes referenced this issue from a commit

2026-02-14 16:34:31 +00:00

Merge pull request #93 from ianrrees/20160213-fix-non-gui-build

Sign in to join this conversation.