diff --git a/.gitignore b/.gitignore index 733b192..4571905 100755 --- a/.gitignore +++ b/.gitignore @@ -59,7 +59,7 @@ Thumbs.db *.ps1 keyring passwords.py *github* -*git* + *tech_spec* dashboards backend/mappings.db diff --git a/specs/011-git-integration-dashboard/checklists/requirements.md b/specs/011-git-integration-dashboard/checklists/requirements.md new file mode 100644 index 0000000..55c7e90 --- /dev/null +++ b/specs/011-git-integration-dashboard/checklists/requirements.md @@ -0,0 +1,34 @@ +# Specification Quality Checklist: Git Integration Plugin for Dashboard Development + +**Purpose**: Validate specification completeness and quality before proceeding to planning +**Created**: 2026-01-18 +**Feature**: [spec.md](../spec.md) + +## Content Quality + +- [x] No implementation details (languages, frameworks, APIs) +- [x] Focused on user value and business needs +- [x] Written for non-technical stakeholders +- [x] All mandatory sections completed + +## Requirement Completeness + +- [x] No [NEEDS CLARIFICATION] markers remain +- [x] Requirements are testable and unambiguous +- [x] Success criteria are measurable +- [x] Success criteria are technology-agnostic (no implementation details) +- [x] All acceptance scenarios are defined +- [x] Edge cases are identified +- [x] Scope is clearly bounded +- [x] Dependencies and assumptions identified + +## Feature Readiness + +- [x] All functional requirements have clear acceptance criteria +- [x] User scenarios cover primary flows +- [x] Feature meets measurable outcomes defined in Success Criteria +- [x] No implementation details leak into specification + +## Notes + +✅ **VALIDATION COMPLETE**: All checklist items pass. The specification is ready for `/speckit.clarify` or `/speckit.plan` \ No newline at end of file diff --git a/specs/011-git-integration-dashboard/spec.md b/specs/011-git-integration-dashboard/spec.md new file mode 100644 index 0000000..b21db18 --- /dev/null +++ b/specs/011-git-integration-dashboard/spec.md @@ -0,0 +1,172 @@ +# Feature Specification: Git Integration Plugin for Dashboard Development + +**Feature Branch**: `011-git-integration-dashboard` +**Created**: 2026-01-18 +**Status**: In Progress +**Input**: User description: "Нужен плагин интеграции git в разработку дашбордов. Требования - возможность настройки целевого git сервера (базово - интеграция с gitlab), хранение и синхронизация веток разработки дашбордов, возможность публикацию в другое целевое окружение после коммита" + +## User Scenarios & Testing *(mandatory)* + + + +### User Story 1 - Configure Git Server Connection (Priority: P1) + +A dashboard developer needs to connect the system to their GitLab server to enable version control for dashboard development. They want to configure the Git server URL, authentication credentials, and repository details through a simple form interface. + +**Why this priority**: This is the foundational requirement - without Git server configuration, no other Git functionality can work. It's the entry point for all Git operations. + +**Independent Test**: Can be fully tested by configuring a GitLab server connection and verifying the connection test succeeds, delivering the ability to establish Git server connectivity. + +**Acceptance Scenarios**: + +1. **Given** a user is on the Git integration settings page, **When** they enter valid GitLab server URL and API token, **Then** the system successfully validates the connection +2. **Given** a user enters invalid GitLab credentials, **When** they test the connection, **Then** the system displays a clear error message indicating authentication failure +3. **Given** a user has configured a Git server, **When** they save the settings, **Then** the configuration is persisted and can be retrieved later + +--- + +### User Story 2 - Dashboard Branch Management (Priority: P1) + +A dashboard developer needs to create, switch between, and manage different development branches for their dashboards. They want to see available branches, create new feature branches, and switch between branches to work on different dashboard versions. + +**Why this priority**: This is core to the Git workflow - developers need to manage branches to work on different features or versions of dashboards simultaneously. + +**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. + +**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 +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 + +--- + +### User Story 3 - Dashboard Synchronization with Git (Priority: P1) + +A dashboard developer needs to synchronize their local dashboard changes with the Git repository. They want to commit changes, push to remote branches, and pull updates from other developers working on the same dashboard. + +**Why this priority**: This enables collaborative development and ensures changes are properly tracked and shared between team members. + +**Independent Test**: Can be fully tested by making dashboard changes, committing them, and pushing to the remote repository, delivering complete Git workflow integration. + +**Acceptance Scenarios**: + +1. **Given** a user has made changes to a dashboard, **When** they commit the changes with a message, **Then** the changes are committed to the current branch +2. **Given** local changes exist, **When** a user pushes to the remote repository, **Then** the changes are successfully pushed and visible to other team members +3. **Given** remote changes exist, **When** a user pulls from the remote repository, **Then** local dashboard content is updated with the latest changes + +--- + +### User Story 4 - Environment Deployment (Priority: P2) + +A dashboard developer needs to deploy their dashboard changes to different target environments (e.g., staging, production) after committing changes. They want to select a target environment and trigger the deployment process. + +**Why this priority**: This enables the complete development-to-production workflow, allowing teams to promote dashboard changes through different environments. + +**Independent Test**: Can be fully tested by selecting a target environment and triggering deployment, delivering the ability to promote dashboard changes to different environments. + +**Acceptance Scenarios**: + +1. **Given** dashboard changes are committed, **When** a user selects a target environment for deployment, **Then** the system validates the deployment configuration +2. **Given** deployment is initiated, **When** the process completes, **Then** the user receives clear feedback on deployment success or failure +3. **Given** multiple environments are configured, **When** a user deploys to one environment, **Then** other environments remain unaffected + +--- + +### User Story 5 - Git History and Change Tracking (Priority: P3) + +A dashboard developer needs to view the commit history and changes made to dashboards over time. They want to see who made changes, when they were made, and what specific changes were included in each commit. + +**Why this priority**: This provides visibility into the development process and helps with debugging, auditing, and understanding the evolution of dashboards. + +**Independent Test**: Can be fully tested by viewing commit history and examining specific commits, delivering transparency into dashboard development history. + +**Acceptance Scenarios**: + +1. **Given** multiple commits exist, **When** a user views the commit history, **Then** they see a chronological list of all commits with relevant details +2. **Given** a specific commit is selected, **When** the user views commit details, **Then** they see the changes included in that commit +3. **Given** commit history is available, **When** a user searches for specific changes, **Then** they can filter and find relevant commits + +--- + +### Edge Cases + +- What happens when Git server is temporarily unavailable during synchronization? +- How does system handle merge conflicts when multiple developers modify the same dashboard? +- What happens when a user tries to deploy to an environment that doesn't exist or is misconfigured? +- How does system handle large dashboard files that exceed Git repository size limits? +- What happens when Git authentication tokens expire during operations? +- How does system handle network interruptions during long-running operations like large pushes? + +## Requirements *(mandatory)* + +## Clarifications + +### Session 2026-01-18 +- Q: What is the primary data format for storing dashboards in the Git repository? → A: YAML files (more human-readable for diffs) +- Q: How should the system handle merge conflicts during synchronization? → A: Built-in UI for basic resolution (Mine/Theirs/Manual) +- Q: What triggers a deployment to a target environment? → A: Manual trigger by user from UI +- Q: How should the system handle authentication with GitLab? → A: Personal Access Token (PAT) +- Q: What should be the scope of a "Dashboard" in the Git repository? → A: Directory per dashboard (metadata + assets) + +### Functional Requirements + +- **FR-001**: System MUST allow users to configure Git server connection settings including server URL, authentication via Personal Access Token (PAT), and repository details +- **FR-002**: System MUST support GitLab as the primary Git server with extensible architecture for other Git servers +- **FR-003**: System MUST validate Git server connection using the provided PAT before saving configuration +- **FR-004**: Users MUST be able to view all available branches from the configured Git repository +- **FR-005**: Users MUST be able to create new branches both locally and remotely with proper naming validation +- **FR-006**: Users MUST be able to switch between existing branches and have dashboard content update accordingly +- **FR-007**: System MUST allow users to commit dashboard changes with commit messages and optional file selection +- **FR-008**: System MUST support pushing local commits to remote repository branches +- **FR-009**: System MUST support pulling changes from remote repository to local working directory +- **FR-010**: System MUST handle merge conflicts with a built-in UI providing "Keep Mine", "Keep Theirs", and "Manual Edit" resolution options +- **FR-011**: Users MUST be able to configure multiple target environments for dashboard deployment +- **FR-012**: System MUST allow users to manually trigger deployment to a selected target environment from the UI +- **FR-013**: System MUST validate deployment configuration before initiating deployment process +- **FR-014**: System MUST provide clear feedback on deployment success or failure with detailed logs +- **FR-015**: Users MUST be able to view commit history with details including author, timestamp, and commit message +- **FR-016**: System MUST display detailed changes included in each commit for audit purposes +- **FR-017**: System MUST handle PAT expiration gracefully with re-authentication prompts +- **FR-018**: System MUST provide offline mode functionality when Git server is unavailable +- **FR-019**: System MUST validate dashboard files before committing to ensure they are properly formatted in YAML within their respective dashboard directories +- **FR-020**: Users MUST be able to search and filter commit history by date, author, or message content +- **FR-021**: System MUST support rollback functionality to previous dashboard versions via Git operations + +### Key Entities *(include if feature involves data)* + +- **GitServerConfig**: Represents Git server connection configuration including server URL, Personal Access Token (PAT), repository path, and connection status +- **Branch**: Represents a Git branch with properties like name, commit hash, last updated timestamp, and remote tracking status +- **Commit**: Represents a Git commit with properties like commit hash, author, timestamp, commit message, and list of changed files +- **Environment**: Represents a deployment target environment with properties like name, URL, authentication details, and deployment status +- **DashboardChange**: Represents changes made to dashboard directories (YAML metadata + assets) including file paths, change type (add/modify/delete), and content differences +- **Branch**: Represents a Git branch with properties like name, commit hash, last updated timestamp, and remote tracking status +- **Commit**: Represents a Git commit with properties like commit hash, author, timestamp, commit message, and list of changed files +- **Environment**: Represents a deployment target environment with properties like name, URL, authentication details, and deployment status +- **DashboardChange**: Represents changes made to dashboard files (YAML format) including file paths, change type (add/modify/delete), and content differences + +## Success Criteria *(mandatory)* + +### Measurable Outcomes + +- **SC-001**: Users can successfully configure a GitLab server connection and validate it within 2 minutes +- **SC-002**: Dashboard branch switching operations complete within 5 seconds for repositories with up to 100 commits +- **SC-003**: Commit and push operations succeed in 95% of attempts under normal network conditions +- **SC-004**: Deployment to target environments completes successfully within 30 seconds for standard dashboard configurations +- **SC-005**: Users can view and navigate through commit history for dashboards with up to 1000 commits without performance degradation +- **SC-006**: Merge conflict resolution guidance is provided in 100% of conflict scenarios with clear resolution steps +- **SC-007**: Authentication token refresh process completes within 10 seconds when tokens expire +- **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