184 lines
10 KiB
Markdown
184 lines
10 KiB
Markdown
# Tasks: Git Integration Plugin
|
|
|
|
**Feature**: Git Integration for Dashboard Development
|
|
**Status**: Completed
|
|
**Total Tasks**: 43
|
|
|
|
## Phase 1: Setup
|
|
**Goal**: Initialize project structure and dependencies.
|
|
|
|
- [x] T001 Install GitPython dependency in `backend/requirements.txt`
|
|
- [x] T002 Create backend directory structure (routes, models, plugins, services)
|
|
- [x] T003 Create frontend directory structure (components, routes, services)
|
|
|
|
## Phase 2: Foundational
|
|
**Goal**: Implement core data models and service skeletons.
|
|
**Prerequisites**: Phase 1
|
|
|
|
- [x] T004 Create Git Pydantic models (Branch, Commit, DashboardChange) in `backend/src/api/routes/git_schemas.py`
|
|
- [x] T005 Create GitServerConfig and Environment SQLAlchemy models in `backend/src/models/git.py`
|
|
- [x] T006 Implement GitService class skeleton with GitPython init in `backend/src/services/git_service.py`
|
|
- [x] T007 Implement GitPlugin class skeleton inheriting PluginBase in `backend/src/plugins/git_plugin.py`
|
|
|
|
## Phase 3: User Story 1 - Configure Git Server (P1)
|
|
**Goal**: Enable users to configure and validate Git server connections.
|
|
**Prerequisites**: Phase 2
|
|
|
|
- [x] T008 [US1] Implement `GitService.test_connection` method in `backend/src/services/git_service.py`
|
|
- [x] T009 [US1] Implement GET/POST `/api/git/config` endpoints in `backend/src/api/routes/git.py`
|
|
- [x] T010 [US1] Create `frontend/src/services/gitService.js` API client
|
|
- [x] T011 [US1] Create `frontend/src/components/tools/ConnectionForm.svelte` (or similar) for Git config
|
|
- [x] T012 [US1] Implement Settings page at `frontend/src/routes/settings/git/+page.svelte`
|
|
|
|
## Phase 4: User Story 2 - Branch Management (P1)
|
|
**Goal**: Enable creating and switching branches for dashboards.
|
|
**Prerequisites**: Phase 3
|
|
|
|
- [x] T013 [US2] Implement `GitService` branch operations (list, create, checkout) in `backend/src/services/git_service.py`
|
|
- [x] T014 [US2] Implement `GitService.init_repo` (clone/init strategy) in `backend/src/services/git_service.py`
|
|
- [x] T015 [US2] Implement GET/POST `/api/git/branches` endpoints in `backend/src/api/routes/git.py`
|
|
- [x] T016 [US2] Implement POST `/api/git/checkout` endpoint in `backend/src/api/routes/git.py`
|
|
- [x] T017 [US2] Create `frontend/src/components/git/BranchSelector.svelte` component
|
|
- [x] T018 [US2] Update Dashboard page to include Git controls container
|
|
|
|
## Phase 5: User Story 3 - Synchronization (P1)
|
|
**Goal**: Enable committing, pushing, and pulling changes.
|
|
**Prerequisites**: Phase 4
|
|
|
|
- [x] T019 [US3] Implement Dashboard export/unpack logic (using SupersetClient/superset_tool) in `backend/src/plugins/git_plugin.py`
|
|
- [x] T020 [US3] Implement `GitService` status and diff generation methods in `backend/src/services/git_service.py`
|
|
- [x] T021 [US3] Implement `GitService` commit, push, and pull methods in `backend/src/services/git_service.py`
|
|
- [x] T022 [US3] Implement `/api/git/sync`, `/commit`, `/push`, `/pull` endpoints in `backend/src/api/routes/git.py`
|
|
- [x] T023 [US3] Create `frontend/src/components/git/CommitModal.svelte` with diff viewer
|
|
- [x] T024 [US3] Create `frontend/src/components/git/ConflictResolver.svelte` (Keep Mine/Theirs UI)
|
|
|
|
## Phase 6: User Story 4 - Deployment (P2)
|
|
**Goal**: Deploy dashboard versions to target environments.
|
|
**Prerequisites**: Phase 5
|
|
|
|
- [x] T025 [US4] Implement Environment CRUD endpoints in `backend/src/api/routes/git.py`
|
|
- [x] T026 [US4] Implement deployment logic (zip packing + Import API) in `backend/src/plugins/git_plugin.py`
|
|
- [x] T027 [US4] Implement POST `/api/git/deploy` endpoint in `backend/src/api/routes/git.py`
|
|
- [x] T028 [US4] Create Deployment modal/interface in `frontend/src/components/git/DeploymentModal.svelte`
|
|
|
|
## Phase 7: User Story 5 - History (P3)
|
|
**Goal**: View commit history and audit changes.
|
|
**Prerequisites**: Phase 5
|
|
|
|
- [x] T029 [US5] Implement `GitService.get_history` method in `backend/src/services/git_service.py`
|
|
- [x] T030 [US5] Implement GET `/api/git/history` endpoint in `backend/src/api/routes/git.py`
|
|
- [x] T031 [US5] Create `frontend/src/components/git/CommitHistory.svelte` component
|
|
- [x] T032 [US5] Integrate History viewer into Dashboard page
|
|
|
|
## Phase 8: Polish & Cross-Cutting
|
|
**Goal**: Finalize error handling, UI feedback, and performance.
|
|
|
|
- [x] T033 Add comprehensive error handling for Git operations (timeouts, auth failures)
|
|
- [x] T034 Add loading states and progress indicators to all Git UI components
|
|
- [x] T035 Verify offline mode behavior and graceful degradation
|
|
|
|
## Dependencies
|
|
|
|
- US1 -> US2 -> US3 -> US4
|
|
- US3 -> US5
|
|
- US1 is the critical path.
|
|
|
|
## Implementation Strategy
|
|
- MVP: Complete US1, US2, and US3 (Configure, Branch, Sync). This allows local-only versioning if remote is optional, or full sync if remote is configured.
|
|
- Incremental: Add Deployment (US4) and History (US5) after core sync workflow is stable.
|
|
|
|
## Phase 9: Operational Debug (2026-03-08)
|
|
**Goal**: Validate mismatch between configured Git server URL and repository origin URL during push flow.
|
|
|
|
- [x] D001 Diagnose source-of-truth mismatch for server URL in push flow
|
|
- [x] D002 Validate diagnosis with backend push diagnostics logs
|
|
- [x] D003 Apply behavioral fix only after diagnosis confirmation
|
|
|
|
## Phase 10: Operational Debug (2026-03-08)
|
|
**Goal**: Diagnose unexpected 409 on pull caused by unfinished merge detection.
|
|
|
|
- [x] D004 Add pull diagnostics logs for merge marker, repo path, branch, and binding metadata
|
|
- [x] D005 Confirm root cause hypothesis from new diagnostics before applying any behavior fix
|
|
- [x] D006 Implement richer 409 API response for unfinished merge (repo path, branch, explicit manual steps)
|
|
|
|
## Phase 11: Operational Debug (2026-03-08)
|
|
**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`
|
|
|
|
## 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 |