ss-tools/specs/011-git-integration-dashboard/plan.md

Implementation Plan: Git Integration Plugin for Dashboard Development

Branch: 011-git-integration-dashboard | Date: 2026-01-22 | Last Updated: 2026-07-01 | Spec: spec.md Input: Feature specification from /specs/011-git-integration-dashboard/spec.md

Summary

Implement a Git integration plugin that allows dashboard developers to version control their Superset dashboards. The plugin will support GitLab, GitHub, and Gitea, enabling branch management, committing/pushing changes (as unpacked Superset exports), and deploying to target environments via the Superset API.

Branch Model

Current Implementation (2026-05-27)

dev → preprod → prod

Environment branches:

• dev — разработка (соответствует DEV stage)
• preprod — предварительное тестирование (соответствует PREPROD stage)
• prod — продакшен (соответствует PROD stage)

Workflow:

1. Разработка ведётся в ветке dev
2. После тестирования изменения продвигаются в preprod через MR
3. После approval изменения мержатся в prod через MR
4. Deploy в Superset происходит только после merge в prod

Future Enhancement (Planned)

feature/auth     ─┐
feature/charts   ─┼─→ dev → preprod → prod
hotfix/bug-123   ─┘

Feature branches:

• feature/* — создаются от dev, мержатся обратно в dev
• hotfix/* — создаются от prod, мержатся в prod и dev

См. Phase 13 в tasks.md для деталей реализации

Implementation Audit (2026-07-01)

The target branch model is dev -> preprod -> prod. A 2026-07-01 implementation remediation closed the critical branch naming drift found during audit:

• Backend defaults now use prod for new repositories and provider payloads.
• Gitflow bootstrap creates prod, dev, and preprod; existing main/master repositories remain legacy-compatible.
• Frontend release UI shows PROD (prod) and same-branch PROD promotion is blocked with an explicit final-state message.
• Branch selection separates environment, feature, hotfix, legacy, other, and remote refs.

Planning implication: Phase 12A is implemented. Phase 13 can build specialized feature/hotfix flows on top of this base, and Phase 14 remains the BI-oriented UX roadmap.

Target User Experience

Primary user: BI developer / Superset analyst.

The product should not feel like a generic Git client. It should feel like a controlled dashboard versioning and publishing workflow:

1. The user sees where the dashboard is in the DEV -> PREPROD -> PROD lifecycle.
2. The user sees the next safe action before raw Git commands.
3. The user can inspect what changed in BI terms before opening YAML diffs.
4. PROD-affecting actions require a confirmation summary.
5. Raw Git concepts remain available for advanced users and troubleshooting.

UX Roadmap

UX Phase A: Branch Model Remediation

1. Done: replaced remaining new-repository main defaults with prod.
2. Done: preserved legacy main/master compatibility as advanced/legacy refs.
3. Done: updated release defaults to dev -> preprod -> prod.
4. Done: added/updated targeted backend and frontend regression coverage around defaults and provider payloads.

UX Phase B: BI-Oriented Git Manager

1. Add a pipeline header with current environment, current branch, sync state, changed artifact count, and recommended next action.
2. Rename primary actions in the UI:
   • Commit -> "Save version" with Commit as secondary terminology.
   • Push -> "Send to remote".
   • Pull -> "Get remote updates".
   • Deploy -> "Publish to environment".
3. Move raw Git details into advanced sections.

UX Phase C: Safer Repository Setup

1. Split setup into "Create new repository" and "Connect existing repository".
2. Show pre-action summary: Git server, repo name, remote URL, default branch prod, and expected environment branches.
3. After successful init, guide to "Sync current Superset dashboard".

UX Phase D: Semantic Change Review

1. Categorize changed files as dashboard metadata, charts, datasets, databases, filters, or other.
2. Show counts and object names before YAML diff.
3. Keep raw diff expandable and searchable.

UX Phase E: Contextual Recovery

1. Replace long-lived global Git operation toasts with modal-scoped error banners.
2. Provide recovery actions for checkout conflicts, unfinished merges, pull conflicts, and push rejection.
3. Keep detailed diagnostics available for developers.

Technical Context

Language/Version: Python 3.9+ (Backend), Node.js 18+ (Frontend) Primary Dependencies: FastAPI, SvelteKit, GitPython (or CLI git), Pydantic, SQLAlchemy, Superset API Storage: SQLite (for config/history), Filesystem (local Git repositories) Testing: pytest (Backend), SvelteKit testing utilities (Frontend) Target Platform: Linux server Project Type: Web application (Frontend + Backend) Performance Goals: Branch switching < 5s, Search/Filter history < 2s Constraints: Offline mode support, Superset API dependency for deployment, PAT-based authentication Scale/Scope: 1 repository per dashboard, support for up to 1000 commits per repo

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

1. Semantic Protocol Compliance: All new modules must include headers, [DEF] anchors, and @RELATION tags as per semantic_protocol.md.
2. Causal Validity: API contracts and data models must be defined in specs/ before implementation.
3. Everything is a Plugin: The Git integration must be implemented as a PluginBase subclass in backend/src/plugins/.
4. Design by Contract: Use Pydantic models for request/response validation and internal state transitions.

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

backend/
├── src/
│   ├── api/routes/git.py        # Git integration endpoints
│   ├── models/git.py            # Git-specific Pydantic/SQLAlchemy models (GitServerConfig, DashboardChange)
│   ├── plugins/git_plugin.py    # PluginBase implementation (1 repo = 1 dashboard logic)
│   └── services/git_service.py  # Core Git logic (GitPython wrapper)
└── tests/
    └── plugins/test_git.py

frontend/
├── src/
│   ├── components/git/          # Git UI components (BranchSelector, CommitModal, ConflictResolver)
│   ├── routes/settings/git/     # Git configuration pages (+page.svelte)
│   └── services/gitService.js   # API client for Git operations

Structure Decision: Web application structure as the project has both FastAPI backend and SvelteKit frontend.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

Implementation Phases

Phase 2: Backend Implementation (Plugin & Service)

1. Data Models: Implement GitServerConfig, Branch, Commit, Environment, and DashboardChange in src/models/git.py.
2. Git Service: Implement GitService using GitPython. Focus on:
   • Repo initialization and cloning (1 repo per dashboard strategy).
   • Branch management (list, create, checkout).
   • Stage, commit, push, pull.
   • History retrieval and diff generation.
3. Git Plugin: Implement GitPlugin(PluginBase).
   • Integrate with superset_tool for exporting dashboards as unpacked YAML files (metadata, charts, datasets).
   • Handle unpacking ZIP exports into the repo structure.
4. API Routes: Implement /api/git/* endpoints for config, sync, and history.

Phase 3: Frontend Implementation

1. Configuration UI: Settings page for GitServerConfig (Provider selection, PAT validation).
2. Dashboard Integration: Add Git controls to the Dashboard view.
   • Branch selector (Create/Switch).
   • Commit/Push/Pull buttons with status indicators.
   • History viewer with search/filter.
3. Conflict Resolution UI: Implementation of "Keep Mine/Theirs" file picker for YAML content.

Phase 4: Deployment Integration

1. Environment Management: CRUD for Environment (Target Superset instances).
2. Deployment Logic: Implement deployment via Superset Import API (POST /api/v1/dashboard/import/).
   • Handle zip packing from Git repo state before import.

Phase 5: Branch Model Remediation (2026-07-01 Audit)

1. Backend defaults:
   • Change Git server default_branch fallback to prod.
   • Ensure _ensure_gitflow_branches creates prod, dev, and preprod.
   • Ensure create_branch defaults to prod only when no better source branch is specified.
   • Ensure GitHub, GitLab, and Gitea repository creation default to prod.
2. Frontend defaults:
   • Change Git manager and branch selector initial branch to prod.
   • Change release pipeline label to PROD (prod).
   • Change PREPROD promotion target from main to prod.
3. Compatibility:
   • Keep existing main/master repositories usable.
   • Present main/master as legacy or advanced refs in normal UI.
4. Verification:
   • Add regression tests for defaults.
   • Browser-check /git release flow on DEV, PREPROD, and PROD environments.

Phase 6: BI Developer UX Hardening

1. Add dashboard lifecycle state to the Git modal.
2. Add semantic change summary above YAML diff.
3. Improve repository initialization guidance.
4. Add modal-scoped recovery states for Git failures.
5. Add PROD publish confirmation summary.

Future Enhancements

Feature & Hotfix Branch Support (Phase 13)

Цель: Расширить модель веток для поддержки параллельной разработки нескольких фич и срочных исправлений.

Приоритет: P2 (после стабилизации базового workflow)

Сложность: ~25-30 часов

Backend Implementation

1. merge_branch — новый метод для слияния веток

   • Merge source_branch в target_branch
   • Обработка конфликтов (abort + показать ошибку)
   • Возврат статуса: success / conflicts

2. delete_branch — удаление веток после merge

   • Запрет удаления environment branches (dev/preprod/prod)
   • Автоматическое удаление после успешного merge (опционально)

3. Расширение list_branches

   • Группировка по типам: Environment / Feature / Hotfix
   • Фильтрация по префиксу (feature/, hotfix/)

4. Branch protection rules (опционально)

   • Запрет прямого push в prod без MR
   • Требование code review для environment branches

Frontend Implementation

1. BranchSelector UI — группированный dropdown

   • Environment branches (dev, preprod, prod)
   • Feature branches (feature/*)
   • Hotfix branches (hotfix/*)

2. Create branch dialog — расширенный UI

   • Выбор типа: feature / hotfix / bugfix
   • Валидация имени (regex: ^[a-zA-Z0-9._\/-]+$)
   • Выбор source branch

3. Merge UI — кнопка merge для feature branches

   • Показ diff перед merge
   • Обработка конфликтов через ConflictResolver
   • Опция auto-delete после merge

4. ReleasePanel — поддержка merge feature → dev

   • Расширенный список source branches
   • Визуализация merge path

Риски и митигации

• Risk: Merge conflicts в YAML файлах могут быть сложными
  • Mitigation: Использовать существующий ConflictResolver, чёткие сообщения об ошибках
• Risk: Branch protection может замедлить workflow для маленьких команд
  • Mitigation: Сделать protection rules опциональными через GitServerConfig
• Risk: Auto-delete может привести к потере работы
  • Mitigation: Требовать явное подтверждение, добавить "undo" на 5 минут

См. tasks.md Phase 13 для детального списка задач