Files
kandev/docs/specs/workspaces/worktree-branch-templates.md
T

64 lines
2.3 KiB
Markdown

---
status: building
created: 2026-08-15
owner: kandev
---
# Worktree Branch Templates
## Why
Teams use repository-specific branch names for tickets and other local rules.
Kandev must preserve each saved template across backend restarts and redeployments.
## What
- Each workspace repository has one worktree branch template.
- A saved valid template replaces the template for that repository.
- A backend restart or schema replay does not change a non-empty saved template.
- A new repository uses `feature/{title}-{suffix}` when the request omits the template.
- An upgrade from the legacy prefix field derives the template once from that prefix.
- The legacy upgrade uses `feature/` when the stored prefix is empty.
The template syntax and placeholders follow
[ADR 0032](../../decisions/0032-configurable-worktree-branch-names.md).
## Data Model
The `repositories` table owns these fields:
| Field | Contract |
| --- | --- |
| `worktree_branch_template` | The current template for the repository. |
| `worktree_branch_prefix` | The legacy prefix used only to upgrade a repository that has no template field. |
## API Surface
The existing repository create, update, and read contracts use the
`worktree_branch_template` field. This repair does not change these contracts.
## Persistence Guarantees
The repository store keeps a saved template across process restarts and deployment
replacements. Startup schema work can initialize a legacy row, but it cannot replace
a non-empty template.
## Scenarios
- **GIVEN** a repository with a custom template, **WHEN** Kandev restarts, **THEN**
the repository still has the exact custom template.
- **GIVEN** a legacy repository with prefix `fix/` and no template field, **WHEN**
Kandev upgrades the database, **THEN** the template becomes
`fix/{title}-{suffix}`.
- **GIVEN** a legacy repository with an empty prefix and no template field,
**WHEN** Kandev upgrades the database, **THEN** the template becomes
`feature/{title}-{suffix}`.
- **GIVEN** a migrated repository whose template was later changed, **WHEN** Kandev
replays startup schema work, **THEN** the changed template remains unchanged.
## Out of Scope
- Recovery of a custom template that an earlier Kandev version already replaced.
- Changes to the template syntax, placeholders, validation, default value, or UI.
- Replacement of the current schema migration system.