codex - added docu

2026-03-25 00:07:30 +01:00
parent 6dee323c6c
commit 82f7608709
16 changed files with 432 additions and 3 deletions
@@ -0,0 +1,24 @@
+# 01 Git Provider Abstraction and Gitea Foundation
+
+## Goal
+
+Introduce the integration foundation in a provider-agnostic way while implementing Gitea as the first actual Git provider.
+
+## Requirements
+
+- Add a Git provider abstraction at the domain and service level.
+- Implement Gitea as the first provider.
+- Keep the ticketing and project domain free from hard-coded Gitea-specific assumptions wherever possible.
+- Design the integration so future providers such as GitHub and GitLab can be added without redesigning project or ticket core models.
+
+## Acceptance Criteria
+
+- The codebase has a clear provider boundary for Git integrations.
+- Gitea-specific logic lives behind that boundary.
+- Project and ticket core logic depend on the provider abstraction, not directly on Gitea client details.
+
+## Out of Scope
+
+- GitHub integration
+- GitLab integration
+- Webhook processing for multiple providers
@@ -0,0 +1,26 @@
+# 02 Project Repository Connections
+
+## Goal
+
+Allow projects to store one or more Gitea repository connections through project settings.
+
+## Requirements
+
+- Add project settings for repository connections.
+- A repository connection must store enough information to identify the provider and repository.
+- The first supported provider is Gitea.
+- A project may have multiple repository connections.
+- Repository connection management must be protected by the appropriate project-level permissions.
+
+## Acceptance Criteria
+
+- An authorized user can add, edit, list, and remove Gitea repository connections for a project.
+- A project can hold more than one repository connection.
+- Repository connections are clearly scoped to their project.
+- The stored data is compatible with the provider abstraction introduced in release `0.2`.
+
+## Out of Scope
+
+- Automatic repository discovery
+- Cross-project shared repository connections
+- Provider credential vault design beyond what is necessary for the first working Gitea integration
@@ -0,0 +1,25 @@
+# 03 Ticket Branch Discovery by Ticket Key
+
+## Goal
+
+Show branches related to a ticket by matching configured repository branches against the ticket key prefix.
+
+## Requirements
+
+- Add a branches section to the ticket detail view.
+- For each configured project repository connection, identify branches whose names start with the ticket key.
+- A matching branch must be shown on the ticket when its name starts with the exact ticket key, for example `AUTH-42-...`.
+- Present matches in a way that makes the repository source clear.
+- The first implementation may use direct fetches or a simple cache, but it must not require a large background sync system.
+
+## Acceptance Criteria
+
+- A ticket with key `AUTH-42` shows branches such as `AUTH-42-login-form`.
+- Branches that do not start with the ticket key are not shown.
+- If multiple connected repositories contain matching branches, the ticket shows matches from each relevant repository.
+
+## Out of Scope
+
+- Commit listing
+- Branch creation from inside KanbanGit
+- Cross-ticket branch disambiguation beyond exact ticket-key prefix matching
@@ -0,0 +1,28 @@
+# 04 Ticket Pull Request Visibility
+
+## Goal
+
+Show pull requests related to a ticket alongside the matching branches in the ticket detail view.
+
+## Requirements
+
+- Add a pull requests section to the ticket detail view.
+- Pull requests must be associated to a ticket using the same ticket-key-based branch naming convention.
+- Show enough pull request information to identify and open the matching item, at minimum:
+    - title
+    - provider identifier or number
+    - repository source
+    - status if available
+- The implementation may derive pull request matches from source branch names.
+
+## Acceptance Criteria
+
+- A ticket shows pull requests whose source branch starts with the ticket key.
+- Pull requests unrelated to the ticket key are not shown.
+- The ticket detail view clearly separates branch matches from pull request matches.
+
+## Out of Scope
+
+- Pull request review actions inside KanbanGit
+- Merge controls
+- Status checks and CI reporting