busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
03557d38cc95a0c38d06daaedf7a081d88b5f88a
ss-tools/specs/011-git-integration-dashboard/plan.md
busya 477e30a9f2 git
2026-05-27 23:24:12 +03:00

9.1 KiB
Raw Blame History

Implementation Plan: Git Integration Plugin for Dashboard Development

Branch: 011-git-integration-dashboard | Date: 2026-01-22 | Last Updated: 2026-05-27 | 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 для деталей реализации

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.

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 для детального списка задач