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

Tasks: Git Integration Plugin

Feature: Git Integration for Dashboard Development Status: Completed with implementation drift identified on 2026-07-01 Total Tasks: 43 baseline tasks, plus remediation and UX backlog below

Phase 1: Setup

Goal: Initialize project structure and dependencies.

• T001 Install GitPython dependency in backend/requirements.txt
• T002 Create backend directory structure (routes, models, plugins, services)
• T003 Create frontend directory structure (components, routes, services)

Phase 2: Foundational

Goal: Implement core data models and service skeletons. Prerequisites: Phase 1

• T004 Create Git Pydantic models (Branch, Commit, DashboardChange) in backend/src/api/routes/git_schemas.py
• T005 Create GitServerConfig and Environment SQLAlchemy models in backend/src/models/git.py
• T006 Implement GitService class skeleton with GitPython init in backend/src/services/git_service.py
• 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

• T008 [US1] Implement GitService.test_connection method in backend/src/services/git_service.py
• T009 [US1] Implement GET/POST /api/git/config endpoints in backend/src/api/routes/git.py
• T010 [US1] Create frontend/src/services/gitService.js API client
• T011 [US1] Create frontend/src/components/tools/ConnectionForm.svelte (or similar) for Git config
• 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

• T013 [US2] Implement GitService branch operations (list, create, checkout) in backend/src/services/git_service.py
• T014 [US2] Implement GitService.init_repo (clone/init strategy) in backend/src/services/git_service.py
• T015 [US2] Implement GET/POST /api/git/branches endpoints in backend/src/api/routes/git.py
• T016 [US2] Implement POST /api/git/checkout endpoint in backend/src/api/routes/git.py
• T017 [US2] Create frontend/src/components/git/BranchSelector.svelte component
• 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

• T019 [US3] Implement Dashboard export/unpack logic (using SupersetClient/superset_tool) in backend/src/plugins/git_plugin.py
• T020 [US3] Implement GitService status and diff generation methods in backend/src/services/git_service.py
• T021 [US3] Implement GitService commit, push, and pull methods in backend/src/services/git_service.py
• T022 [US3] Implement /api/git/sync, /commit, /push, /pull endpoints in backend/src/api/routes/git.py
• T023 [US3] Create frontend/src/components/git/CommitModal.svelte with diff viewer
• 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

• T025 [US4] Implement Environment CRUD endpoints in backend/src/api/routes/git.py
• T026 [US4] Implement deployment logic (zip packing + Import API) in backend/src/plugins/git_plugin.py
• T027 [US4] Implement POST /api/git/deploy endpoint in backend/src/api/routes/git.py
• 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

• T029 [US5] Implement GitService.get_history method in backend/src/services/git_service.py
• T030 [US5] Implement GET /api/git/history endpoint in backend/src/api/routes/git.py
• T031 [US5] Create frontend/src/components/git/CommitHistory.svelte component
• T032 [US5] Integrate History viewer into Dashboard page

Phase 8: Polish & Cross-Cutting

Goal: Finalize error handling, UI feedback, and performance.

• T033 Add comprehensive error handling for Git operations (timeouts, auth failures)
• T034 Add loading states and progress indicators to all Git UI components
• 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.

• D001 Diagnose source-of-truth mismatch for server URL in push flow
• D002 Validate diagnosis with backend push diagnostics logs
• 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.

• D004 Add pull diagnostics logs for merge marker, repo path, branch, and binding metadata
• D005 Confirm root cause hypothesis from new diagnostics before applying any behavior fix
• 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.

• D007 Implement unresolved-merge resolution dialog in frontend/src/components/git/GitManager.svelte
• 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: Target completed in spec, implementation drift found on 2026-07-01

Audit Finding (2026-07-01)

Live UI and source inspection show remaining main usage in backend defaults and frontend release flow. Treat the checked items below as intended migration scope, not as verified current behavior.

Backend Changes

• B001 Update _ensure_gitflow_branches to create prod, dev, preprod instead of main, dev, preprod
• B002 Update create_branch default parameter from main to prod
• B003 Update remote providers (GitHub, GitLab, Gitea) to use prod as default_branch

Frontend Changes

• F001 Update BranchSelector.svelte default currentBranch from main to prod
• F002 Update GitManager.svelte initial state from main to prod
• F003 Update GitReleasePanel.svelte UI label from PROD (main) to PROD (prod)
• F004 Update git-utils.js promote defaults: preprod → prod instead of preprod → main

Tests

• T001 Update all test fixtures from main to prod in gitService.test.js

Phase 12A: Branch Naming Remediation (Required)

Goal: Bring implementation back in line with the dev -> preprod -> prod branch model. Status: Implemented 2026-07-01 Priority: P0 Prerequisites: Current baseline Git workflow must remain operational.

Backend Remediation

• R001 Change GitServerConfig.default_branch fallback from main to prod
• R002 Change GitServerConfigBase.default_branch schema fallback from main to prod
• R003 Update _ensure_gitflow_branches to create/use prod, dev, preprod, with prod replacing main as production branch
• R004 Update generic feature branch creation default source from main to dev
• R005 Update GitHub repository creation default branch from main to prod
• R006 Update GitLab repository creation default branch from main to prod
• R007 Update Gitea repository creation default branch from main to prod
• R008 Preserve legacy main/master compatibility for existing repositories without promoting those names as defaults
• R009 Add/update backend regression tests for provider default branch payloads and API model defaults

Frontend Remediation

• R010 Update GitManagerModel initial currentBranch from main to prod
• R011 Update BranchModel and BranchSelector default branch from main to prod
• R012 Update applyGitflowStageDefaults: PREPROD promotes preprod -> prod
• R013 Update GitReleasePanel pipeline label to PROD (prod)
• R014 Prevent main -> main release action; show "No next promotion from PROD" or deploy/rollback options
• R015 Add/update frontend regression tests for branch/release payload defaults
• R016 Browser-validate /git branch selector and release flow after fixes

Documentation Remediation

• R017 Update API contract examples from main to prod
• R018 Update quickstart to describe BI-friendly DEV -> PREPROD -> PROD workflow
• R019 Re-run this spec audit and mark Phase 12 as verified after tests/browser checks pass

Phase 13: Feature & Hotfix Branch Support (Completed)

Goal: Расширить модель веток для поддержки параллельной разработки нескольких фич и срочных исправлений. Status: Completed 2026-07-01 Priority: P2 Estimated Effort: 25-30 hours

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][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 (38 tests, all pass)
• 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

Phase 14: BI Developer UX Improvements (Planned)

Goal: Make Git management understandable and safe for BI developers and Superset analysts. Status: Planned Priority: P1 after Phase 12A Estimated Effort: 20-30 hours

UX Foundation

• U001 Add Git modal pipeline header: DEV (dev) -> PREPROD (preprod) -> PROD (prod)
• U002 Show current branch, lifecycle stage, changed file count, and recommended next action
• U003 Rename primary UI actions to BI workflow terms while keeping Git terms as secondary labels
• U004 Move raw Git diagnostics into advanced sections. Raw diff and repository status payload are now behind expandable advanced sections.

Branch UX

• U010 Redesign branch selector groups: Environment, Feature, Hotfix, Legacy/Advanced
• U011 Hide or de-emphasize origin/* remote refs in the primary selector
• U012 Mark main/master as legacy when present
• U013 Add branch type badges and explanatory tooltips. Branch selector now shows ENV/FEATURE/HOTFIX/LEGACY badges with titles.

Repository Setup UX

• U020 Split setup into "Create new repository" and "Connect existing repository". Init panel now has a segmented create/connect flow.
• U021 Show pre-action summary: default branch prod and branches to create
• U022 After initialization, guide the user to sync the current Superset dashboard. Init copy and workspace empty state point users to Sync after repository binding.
• U023 Add empty/error states for no configured Git servers and invalid remote URL. Init panel now has explicit no-server and URL validation states.

Change Review UX

• U030 Add semantic change summary above YAML diff
• U031 Categorize changes into charts, datasets, dashboard metadata, databases, filters, and other files
• U032 Rename LLM button to "Generate description"
• U033 Add commit message templates for common BI changes
• U034 Keep raw YAML diff expandable and searchable

Release and Deploy Guardrails

• U040 Add PROD action confirmation summary: dashboard name, source branch, target environment, last commit, author, changed files. Implemented in the Git manager deploy confirmation with backend last_commit_* status metadata.
• U041 Require reason for direct merge and show audit warning. Direct mode now shows audit warning, requires reason, and disables promote until provided.
• U042 Replace invalid PROD promotion states with deploy/rollback options
• U043 Add rollback entry points from history and PROD state. Commit history now exposes rollback-by-revert, and PROD operations link users to history rollback.

Error Recovery UX

• U050 Move checkout blocking errors from global sticky toasts into modal-scoped banners
• U051 Provide recovery actions: save version, inspect files, open conflict resolver, retry, dismiss. Merge recovery dialog exposes continue/save, command inspection, conflict resolver, refresh/retry, abort, and dismiss actions.
• U052 Keep detailed backend diagnostics available in expandable sections. Workspace advanced diagnostics exposes the raw repository status payload.
• U053 Add browser tests for checkout conflict, unfinished merge, push rejected, and no-repo setup states. Added Playwright browser-state coverage in frontend/e2e/tests/git.e2e.js.

Success Criteria

• A BI developer can identify the next safe action within 10 seconds of opening Git management.
• New repo setup clearly communicates branch model before making changes.
• PROD-affecting actions always show target and source context before execution.
• Legacy main/master refs do not confuse the primary prod workflow.