git

2026-05-27 23:24:12 +03:00
parent d2c60c87e2
commit 477e30a9f2
36 changed files with 1348 additions and 306 deletions
--- a/specs/011-git-integration-dashboard/plan.md
+++ b/specs/011-git-integration-dashboard/plan.md
@@ -1,12 +1,43 @@
 # Implementation Plan: Git Integration Plugin for Dashboard Development

-**Branch**: `011-git-integration-dashboard` | **Date**: 2026-01-22 | **Spec**: [spec.md](specs/011-git-integration-dashboard/spec.md)
+**Branch**: `011-git-integration-dashboard` | **Date**: 2026-01-22 | **Last Updated**: 2026-05-27 | **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 для деталей реализации**
+
 ## Technical Context

 **Language/Version**: Python 3.9+ (Backend), Node.js 18+ (Frontend)
@@ -98,3 +129,61 @@ frontend/
 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 для детального списка задач**
--- a/specs/011-git-integration-dashboard/spec.md
+++ b/specs/011-git-integration-dashboard/spec.md
@@ -2,9 +2,36 @@

 **Feature Branch**: `011-git-integration-dashboard`  
 **Created**: 2026-01-18  
-**Status**: In Progress
+**Status**: In Progress  
+**Last Updated**: 2026-05-27  
 **Input**: User description: "Нужен плагин интеграции git в разработку дашбордов. Требования - возможность настройки целевого git сервера (базово - интеграция с gitlab), хранение и синхронизация веток разработки дашбордов, возможность публикацию в другое целевое окружение после коммита"

+## Completed Changes
+
+### Branch Naming Convention Update (2026-05-27)
+
+**Изменение**: Переименование ветки `main` → `prod` для соответствия environment stages.
+
+**Причина**: 
+- Устранение путаницы между Git ветками и environment stages
+- Единая терминология: `dev` → `preprod` → `prod`
+- Упрощение ментальной модели для пользователей
+
+**Что было сделано**:
+- Backend: `_ensure_gitflow_branches` теперь создаёт `prod`, `dev`, `preprod`
+- Backend: `create_branch` default parameter изменён на `prod`
+- Backend: Remote providers (GitHub, GitLab, Gitea) используют `prod` как default_branch
+- Frontend: `BranchSelector` default currentBranch = `prod`
+- Frontend: `GitManager` initial state = `prod`
+- Frontend: `GitReleasePanel` UI label: `PROD (prod)`
+- Frontend: `git-utils.js` promote defaults: `preprod → prod`
+- Tests: Обновлены все тесты с `main` на `prod`
+
+**Backward Compatibility**:
+- Существующие репозитории с веткой `main` продолжают работать
+- Новые репозитории создаются с веткой `prod`
+- Миграция не требуется (пользователь подтвердил)
+
 ## User Scenarios & Testing *(mandatory)*

 <!--
@@ -44,11 +71,17 @@ A dashboard developer needs to create, switch between, and manage different deve

 **Independent Test**: Can be fully tested by creating a new branch, switching to it, and verifying the branch operations work correctly, delivering basic Git branch workflow capabilities.

+**Branch Model** (updated 2026-05-27):
+- **Environment branches**: `dev`, `preprod`, `prod` (соответствуют environment stages DEV, PREPROD, PROD)
+- **Feature branches**: `feature/*` (создаются от `dev`, мержатся обратно в `dev`)
+- **Hotfix branches**: `hotfix/*` (создаются от `prod`, мержатся в `prod` и `dev`)
+
 **Acceptance Scenarios**:

-1. **Given** a Git server is configured, **When** a user views the branch list, **Then** they see all available branches from the remote repository
-2. **Given** a user wants to create a new feature branch, **When** they specify a branch name, **Then** the system creates the branch both locally and pushes it to the remote repository
+1. **Given** a Git server is configured, **When** a user views the branch list, **Then** they see all available branches from the remote repository grouped by type (Environment / Feature / Hotfix)
+2. **Given** a user wants to create a new feature branch, **When** they specify a branch name and select source branch, **Then** the system creates the branch both locally and pushes it to the remote repository
 3. **Given** multiple branches exist, **When** a user switches to a different branch, **Then** the dashboard content updates to reflect the selected branch's state
+4. **Given** a feature branch is complete, **When** a user merges it to dev, **Then** the system performs the merge and optionally deletes the feature branch

 ---

@@ -169,3 +202,75 @@ A dashboard developer needs to view the commit history and changes made to dashb
 - **SC-008**: System maintains dashboard state consistency across branch switches in 99% of operations
 - **SC-009**: Deployment rollback operations complete within 1 minute for standard dashboard configurations
 - **SC-010**: Users can search and filter commit history with results displayed within 2 seconds for repositories with up to 500 commits
+
+## Future Enhancements
+
+### Feature & Hotfix Branch Support (Planned)
+
+**Цель**: Расширить модель веток для поддержки параллельной разработки нескольких фич и срочных исправлений.
+
+**Модель веток**:
+```
+feature/auth     ─┐
+feature/charts   ─┼─→ dev → preprod → prod
+hotfix/bug-123   ─┘
+```
+
+**Функциональные требования**:
+
+#### Backend
+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
+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
+
+**Сложность реализации**: ~25-30 часов
+
+**Приоритет**: P2 (после стабилизации базового workflow)
+
+**Зависимости**:
+- Стабильная работа базового Git workflow (US1-US3)
+- Тестирование merge конфликтов
+- UI/UX дизайн для branch management
+
+**Риски**:
+- Merge conflicts могут быть сложными для dashboard YAML файлов
+- Branch protection может замедлить workflow для маленьких команд
+- Auto-delete может привести к потере работы если не настроено правильно
+
+**Рекомендации**:
+- Начать с минимальной реализации (только feature branches)
+- Добавить hotfix branches позже если потребуется
+- Branch protection сделать опциональным через настройки
--- a/specs/011-git-integration-dashboard/tasks.md
+++ b/specs/011-git-integration-dashboard/tasks.md
@@ -105,4 +105,80 @@
 **Goal**: Add GitManager remediation dialog for unfinished merge 409 with actionable guidance.

 - [x] D007 Implement unresolved-merge resolution dialog in `frontend/src/components/git/GitManager.svelte`
- [x] D008 Add frontend contract test for unfinished-merge dialog behavior in `frontend/src/components/git/__tests__/git_manager.unfinished_merge.integration.test.js`
+- [x] D008 Add frontend contract test for unfinished-merge dialog behavior in `frontend/src/components/git/__tests__/git_manager.unfinished_merge.integration.test.js`
+
+## Phase 12: Branch Naming Convention Update (2026-05-27)
+**Goal**: Переименование ветки `main` → `prod` для соответствия environment stages.
+**Status**: Completed
+
+### Backend Changes
+- [x] B001 Update `_ensure_gitflow_branches` to create `prod`, `dev`, `preprod` instead of `main`, `dev`, `preprod`
+- [x] B002 Update `create_branch` default parameter from `main` to `prod`
+- [x] B003 Update remote providers (GitHub, GitLab, Gitea) to use `prod` as default_branch
+
+### Frontend Changes
+- [x] F001 Update `BranchSelector.svelte` default currentBranch from `main` to `prod`
+- [x] F002 Update `GitManager.svelte` initial state from `main` to `prod`
+- [x] F003 Update `GitReleasePanel.svelte` UI label from `PROD (main)` to `PROD (prod)`
+- [x] F004 Update `git-utils.js` promote defaults: `preprod → prod` instead of `preprod → main`
+
+### Tests
+- [x] T001 Update all test fixtures from `main` to `prod` in `gitService.test.js`
+
+## Phase 13: Feature & Hotfix Branch Support (Planned)
+**Goal**: Расширить модель веток для поддержки параллельной разработки нескольких фич и срочных исправлений.
+**Status**: Planned
+**Priority**: P2
+**Estimated Effort**: 25-30 hours
+**Prerequisites**: Phase 12 completed, stable base Git workflow
+
+### Backend Implementation
+- [ ] B010 Implement `merge_branch` method in `GitService` for merging source_branch into target_branch
+- [ ] B011 Add conflict detection and handling in `merge_branch` (abort on conflicts, return status)
+- [ ] B012 Implement `delete_branch` method with protection for environment branches (dev/preprod/prod)
+- [ ] B013 Extend `list_branches` to group branches by type (Environment / Feature / Hotfix)
+- [ ] B014 Add branch name validation (regex: `^[a-zA-Z0-9._\/-]+$`, no `..`, no leading `/`)
+- [ ] B015 Implement branch protection rules (optional: require MR for prod)
+- [ ] B016 Add POST `/api/git/merge` endpoint for branch merging
+- [ ] B017 Add DELETE `/api/git/branches/{name}` endpoint for branch deletion
+- [ ] B018 Add unit tests for merge_branch with conflict scenarios
+- [ ] B019 Add integration tests for feature branch workflow (create → commit → merge → delete)
+
+### Frontend Implementation
+- [ ] F010 Redesign `BranchSelector.svelte` with grouped dropdown (Environment / Feature / Hotfix)
+- [ ] F011 Create `CreateBranchDialog.svelte` with type selection (feature/hotfix/bugfix), name validation, source branch selection
+- [ ] F012 Add merge button to `GitManager.svelte` for feature branches (visible when currentBranch starts with `feature/`)
+- [ ] F013 Create `MergeDialog.svelte` with diff preview, conflict handling, auto-delete option
+- [ ] F014 Extend `GitReleasePanel.svelte` to support merge from feature branches to dev
+- [ ] F015 Add branch type badges (Environment / Feature / Hotfix) with color coding
+- [ ] F016 Implement branch deletion UI with confirmation dialog
+- [ ] F017 Add i18n keys for new branch management features (en/ru)
+- [ ] F018 Add UX tests for branch creation and merge workflows
+- [ ] F019 Add integration tests for feature branch lifecycle
+
+### Documentation
+- [ ] D010 Update user guide with feature branch workflow
+- [ ] D011 Add branch naming conventions to documentation
+- [ ] D012 Create troubleshooting guide for merge conflicts
+
+### Dependencies
+- B010 → B011 → B016 (merge implementation chain)
+- B012 → B017 (delete implementation)
+- B013 → F010 (grouped list → UI)
+- F011 → F013 (create dialog → merge dialog)
+- All backend tasks should be completed before frontend tasks
+
+### Risks & Mitigations
+- **Risk**: Merge conflicts in YAML files may be complex
+  - **Mitigation**: Use existing ConflictResolver component, provide clear error messages
+- **Risk**: Branch protection may slow down workflow for small teams
+  - **Mitigation**: Make protection rules optional via GitServerConfig settings
+- **Risk**: Auto-delete may cause work loss if misconfigured
+  - **Mitigation**: Require explicit confirmation, add "undo" option for 5 minutes
+
+### Success Criteria
+- Users can create feature branches from dev with proper naming validation
+- Users can merge feature branches back to dev with conflict resolution
+- Users can delete feature branches after successful merge
+- Branch list is grouped by type for easy navigation
+- Merge conflicts are handled gracefully with clear user guidance