tasks ready

specs/011-git-integration-dashboard/research.md

@@ -0,0 +1,34 @@
+# Research: Git Integration Plugin
+
+## Unknowns & Clarifications
+
+1. **Git Library**: Should we use `GitPython` or call `git` CLI directly?
+   - **Decision**: Use `GitPython`.
+   - **Rationale**: It provides a high-level API for Git operations, making it easier to handle branches, commits, and remotes programmatically compared to parsing CLI output.
+   - **Alternatives considered**: `pygit2` (faster but requires libgit2), `subprocess.run(["git", ...])` (simple but brittle).
+
+2. **Git Provider API Integration**: How to handle different providers (GitHub, GitLab, Gitea) for connection testing?
+   - **Decision**: Use a unified provider interface with provider-specific implementations.
+   - **Rationale**: While Git operations are standard, testing connections and potentially creating repositories might require provider-specific REST APIs.
+   - **Alternatives considered**: Generic Git clone test (slower, requires local disk space).
+
+3. **Superset Export/Import**: How to handle the "unpacked" requirement?
+   - **Decision**: Use the existing `superset_tool` logic or similar to export as ZIP and then unpack to the Git directory.
+   - **Rationale**: Superset's native export is a ZIP. To fulfill FR-019, we must unpack this ZIP into the repository structure.
+
+4. **Merge Conflict UI**: How to implement "Keep Mine/Theirs" in a web UI?
+   - **Decision**: Implement a file-based conflict resolver in the Frontend.
+   - **Rationale**: Since the data is YAML, we can show a list of conflicting files and let the user pick the version.
+   - **Alternatives considered**: Full 3-way merge UI (too complex for MVP).
+
+## Best Practices
+
+- **Security**: Never store PATs in plain text in logs. Use environment variables or encrypted storage if possible (though SQLite is the current project standard).
+- **Concurrency**: Git operations on the same repository should be serialized to avoid index locks.
+- **Repository Isolation**: Each dashboard gets its own directory/repository to prevent cross-dashboard pollution.
+
+## Findings Consolidations
+
+- **Decision**: Use `GitPython` for core Git logic.
+- **Decision**: Use Provider-specific API clients for connection validation.
+- **Decision**: Unpack Superset exports into `dashboard/`, `charts/`, `datasets/`, `databases/` directories.