283 lines
8.6 KiB
Markdown
283 lines
8.6 KiB
Markdown
# KanbanGit Product Specification
|
|
|
|
## Purpose
|
|
|
|
KanbanGit is a self-hostable project and workflow management application. Its initial product goal is to support project-based Kanban work management with configurable board structure, configurable ticket metadata, ticket hierarchy, auditability, and a future repository integration workflow.
|
|
|
|
This document describes the intended product behavior. It does not claim that these capabilities exist in the current fresh Laravel 13 starter application.
|
|
|
|
## Current implementation status
|
|
|
|
- The repository currently contains the default Laravel 13 + Inertia starter structure.
|
|
- No Kanban, ticket, permission, team, project, or Git integration domain has been implemented yet.
|
|
- This specification is the source of truth for the upcoming product implementation.
|
|
|
|
## Product goals
|
|
|
|
- Support multiple projects inside one self-hosted installation.
|
|
- Provide a configurable board and backlog per project.
|
|
- Support tickets with structured metadata, hierarchy, linking, blockers, and change history.
|
|
- Support application administration and project-level access control.
|
|
- Prepare the product for repository-aware workflows, starting with Gitea.
|
|
|
|
## Roles
|
|
|
|
### Platform admin
|
|
|
|
A platform admin can manage application-wide administrative settings and user administration. This role exists above project-level permissions.
|
|
|
|
### Project member
|
|
|
|
A project member may receive project permissions directly or through one or more teams. Project permissions are scoped to a single project.
|
|
|
|
## Project behavior
|
|
|
|
Each project must include the following product areas:
|
|
|
|
- Board
|
|
- Backlog
|
|
- Project settings
|
|
- Ticket management
|
|
- Future roadmap support
|
|
|
|
### Project creation
|
|
|
|
When a project is created, it must define:
|
|
|
|
- A project name
|
|
- A project key
|
|
|
|
Project key rules:
|
|
|
|
- Maximum length: 5 characters
|
|
- Automatically stored and displayed in uppercase
|
|
- Unique across the entire application
|
|
- Immutable after ticket creation begins, unless a future migration strategy is explicitly designed
|
|
|
|
The project key is used as the prefix for all ticket keys in that project.
|
|
|
|
## Board and backlog
|
|
|
|
Each project has one board and one backlog.
|
|
|
|
Board rules:
|
|
|
|
- The board supports any number of columns.
|
|
- Board columns are configured in project settings.
|
|
- Board columns define the valid in-board statuses for tickets.
|
|
|
|
Backlog rules:
|
|
|
|
- Every newly created ticket starts in the backlog.
|
|
- A backlog ticket is not yet visible in the board columns.
|
|
- When a ticket is assigned to a board column status, it appears on the board.
|
|
- Tickets may move between backlog and board statuses according to future workflow rules.
|
|
|
|
## Roadmap
|
|
|
|
Roadmap support belongs to the intended product surface of a project, but it is currently out of scope for the first implementation phases.
|
|
|
|
## Ticket behavior
|
|
|
|
Tickets are the primary work items inside a project.
|
|
|
|
### Required ticket attributes
|
|
|
|
Every ticket must support:
|
|
|
|
- Immutable ticket key
|
|
- Title
|
|
- Description
|
|
- Acceptance criteria
|
|
- Status
|
|
- Type
|
|
- Priority
|
|
- Optional parent ticket
|
|
- Configurable project-defined field values
|
|
- Links to other tickets
|
|
- Blocked state with comment
|
|
- Worklog
|
|
- Future branch references
|
|
- Future pull request references
|
|
|
|
### Ticket key
|
|
|
|
Ticket keys follow the format `PROJECTKEY-INDEX`.
|
|
|
|
Rules:
|
|
|
|
- `PROJECTKEY` is the uppercase project key.
|
|
- `INDEX` is a monotonically increasing project-local integer sequence.
|
|
- The full ticket key is immutable.
|
|
- Ticket title is not unique.
|
|
- Multiple tickets may share the same title, even within the same project.
|
|
- The ticket key is the only guaranteed unique human-readable identifier for a ticket.
|
|
|
|
### Ticket status
|
|
|
|
Tickets support two status contexts:
|
|
|
|
- `Backlog`
|
|
- One configured board column
|
|
|
|
Only tickets assigned to a board column appear on the board.
|
|
|
|
### Ticket type
|
|
|
|
Each project can configure its own ticket type labels in project settings. Two types must always exist:
|
|
|
|
- `Task`
|
|
- `Parent`
|
|
|
|
Rules:
|
|
|
|
- `Task` and `Parent` are built-in types.
|
|
- Built-in types cannot be deleted.
|
|
- Built-in types may be renamed per project.
|
|
- Additional custom types may be added per project.
|
|
- Tickets of any type may have a parent ticket.
|
|
- Only tickets of type `Parent` may act as the parent of another ticket.
|
|
|
|
### Ticket hierarchy
|
|
|
|
Hierarchy rules:
|
|
|
|
- A ticket may have zero or one parent ticket.
|
|
- A parent ticket must be a ticket whose type is `Parent`.
|
|
- A parent ticket may itself have a parent ticket.
|
|
- This allows nested parent structures.
|
|
- Parent tickets must show their child tickets in a list.
|
|
- Nested child structures should be presented with indentation or another clear hierarchy indicator.
|
|
|
|
### Ticket priority
|
|
|
|
Each project defines its own list of priorities in project settings.
|
|
|
|
Rules:
|
|
|
|
- The available priority options are project-specific.
|
|
- A ticket stores one priority value from the project's configured list.
|
|
|
|
### Configurable ticket fields
|
|
|
|
Each project may define additional ticket field definitions in project settings.
|
|
|
|
A field definition includes at least:
|
|
|
|
- Label
|
|
- Type
|
|
|
|
Initial supported field-definition types include:
|
|
|
|
- User
|
|
- Number
|
|
|
|
Examples:
|
|
|
|
- `Assignee` as a user field
|
|
- `Driver` as a user field
|
|
- `Reviewer` as a user field
|
|
- `Reporter` as a user field
|
|
- `Estimated Story Points` as a number field
|
|
|
|
The field system must be designed to support additional field types in the future.
|
|
|
|
### Ticket links
|
|
|
|
Tickets may be linked to other tickets.
|
|
|
|
Rules:
|
|
|
|
- Link types are project-configurable labels.
|
|
- A linked ticket is represented as part of a ticket list on each side of the relationship.
|
|
- The implementation may later distinguish directionality, but the first documented requirement is label-based ticket linking configured per project.
|
|
|
|
### Ticket blockers
|
|
|
|
Tickets can be marked as blocked.
|
|
|
|
Blocked rules:
|
|
|
|
- Blocking requires a comment.
|
|
- Blocked tickets must be visually distinguished on the board.
|
|
- The target visual language is a warning or danger style such as orange or red.
|
|
|
|
### Ticket worklog
|
|
|
|
Each ticket must have a worklog.
|
|
|
|
Worklog rules:
|
|
|
|
- The worklog records every change to the ticket.
|
|
- Each worklog entry must record who performed the change.
|
|
- The worklog is part of the canonical ticket history.
|
|
|
|
Expected worklog-triggering changes include:
|
|
|
|
- Ticket creation
|
|
- Title, description, or acceptance criteria edits
|
|
- Status changes
|
|
- Type changes
|
|
- Priority changes
|
|
- Parent changes
|
|
- Custom field value changes
|
|
- Link changes
|
|
- Blocked or unblocked state changes
|
|
|
|
## Permissions
|
|
|
|
The product must support both global administration and project-scoped permissions.
|
|
|
|
Global permission behavior:
|
|
|
|
- Platform admins can manage application-wide administrative settings.
|
|
- Platform admins can manage users.
|
|
|
|
Project permission behavior:
|
|
|
|
- Project permissions include `create`, `view`, `edit`, and `delete`.
|
|
- Project permissions may be assigned directly to users.
|
|
- Project permissions may be assigned to teams.
|
|
- Users inherit project permissions from their teams.
|
|
|
|
The full permission system is not implemented in this step, but the product must be built with this model in mind.
|
|
|
|
## Future Git integration
|
|
|
|
The next major feature after the Kanban foundation is Git provider integration.
|
|
|
|
Initial expectations:
|
|
|
|
- Project settings can store one or more repository connections.
|
|
- The first supported provider is Gitea.
|
|
- Later providers should include GitHub and potentially GitLab.
|
|
- Tickets will later expose branch and pull request sections.
|
|
- The ticket branch section should eventually allow users to create a new branch directly from the ticket detail view.
|
|
|
|
Ticket-to-Git matching rule:
|
|
|
|
- A branch or pull request belongs to a ticket when its branch name starts with the ticket key.
|
|
|
|
Branch creation expectations:
|
|
|
|
- The ticket detail view may expose a branch creation action inside the branch section.
|
|
- The branch creation flow should let the user choose from all project-linked repositories.
|
|
- Repository choices remain visible even when the current user has no matching personal Git connection.
|
|
- If the user lacks access to the selected repository, branch creation fields must stay disabled and guide the user to their Git connection settings.
|
|
- The suggested branch name should start from the ticket key plus a title-derived suffix and remain editable before creation.
|
|
- The UI should validate that the proposed branch name is syntactically acceptable and not already taken before creation is submitted.
|
|
|
|
Example:
|
|
|
|
- Ticket key: `AUTH-42`
|
|
- Matching branch: `AUTH-42-login-form`
|
|
|
|
## Explicitly out of scope for now
|
|
|
|
- Implementing roadmap features
|
|
- Supporting GitHub or GitLab in the first Git integration step
|
|
- Implementing the full permission and team management UI in this documentation step
|
|
- Finalizing database schema details
|
|
- Finalizing API contracts
|
|
- Finalizing automation, notifications, or reporting features
|