# 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](specs/011-git-integration-dashboard/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)

```text
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)

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