Version Lifecycle Flow -- TalkIDE Internal Docs

TalkIDE internal documentation

Verze reprezentuje konkrétní bod v životě projektu — semver MAJOR.MINOR.PATCH (např. 0.1.4). Verze vzniká automaticky při každém commitu (PATCH bump) nebo manuální user akcí (MINOR/MAJOR bump). Vzniklá verze je Pending — do PROD se dostane až po explicitním user Publish.

Tento flow popisuje životní cyklus jedné verze. Související state machine projektu (DRAFT/PUBLISHED/UPDATED) viz Project Management Flow. Detailní design publish workflow viz ADR-022.

Vztah Version ↔ Project ↔ Git tag ↔ K8s deployment

Vrstva	Reprezentace verze
TalkIDE BE DB	Tabulka `versions` (id, project_id, semver, sha, published, published_at)
User-app working tree	`build.gradle.kts` line `version = "X.Y.Z"`, `package.json` field `"version": "X.Y.Z"`
Git	Lightweight tag `vX.Y.Z` (vytvořen při Publish, ukazuje na `versions.sha`)
Container Registry	Image tag `<slug>:<semver>` (vytvořen Kaniko buildem při Publish)
Kubernetes (PROD)	`Deployment.spec.template.spec.containers[0].image` ukazuje na `<slug>:<semver>`
Kubernetes (DEV)	Image tag = sha; verze v souborech zachycena, ale URL je `{projectUuid}.talkide.app`

Initial verze: 0.1.0 při Create Project (Mara scaffolding).

Single source of truth: tabulka versions. Soubory + git tag + image tag jsou deriváty, BE je drží v sync.

Životní cyklus verze (state diagram)

stateDiagram-v2
    [*] --> Pending: Commit triggers PATCH bump (or manual MINOR/MAJOR)

    Pending --> Building: User clicks Publish (selects this version)
    Pending --> [*]: Project deleted (cascade)

    Building --> Published: Build + deploy + ingress success, git tag created
    Building --> Failed: Build, deploy or ingress failed

    Failed --> Building: User retries Publish
    Failed --> [*]: Superseded by new version (still in Failed historically)

    Published --> RolledBack: User publishes a different version (this one is no longer live)
    Published --> [*]: Project deleted (cascade)

    RolledBack --> Building: User publishes this version again (rollback-as-publish)
    RolledBack --> [*]: Project deleted (cascade)

Stavy

State	DB reprezentace	Description
Pending	`published=false`, `published_at=NULL`	Verze vznikla bumpem, ale ještě nebyla v PROD
Building	`published=false`, projekt v `BUILDING` stavu, `versions.build_id` set	Aktivní PROD build/deploy běží pro tuto verzi
Published	`published=true`, `published_at=<ts>`	Verze je nebo byla v PROD; aktuálně live verze = `MAX(published_at) WHERE published=true`
Failed	`published=false`, asociovaný `builds.status=FAILED`	Build/deploy selhal; user může retry
RolledBack	`published=true`, ale není `MAX(published_at)`	Historicky publishnutá, později superseded jinou verzí

RolledBack není explicitní DB flag — je to odvozený stav (published, ale ne aktuálně nejnovější published). UI to zobrazuje pro audit a “Republish” akci.

Trigger události

Event	Trigger	DB akce	Side effects
Bump (PATCH)	Git post-commit hook na user/agent commit	`INSERT versions(semver, sha, published=false)`, `UPDATE projects.current_version`	Zápis do `build.gradle.kts` + `package.json`, follow-up bump commit s `[skip-bump]`, status `PUBLISHED → UPDATED`
Bump (MINOR/MAJOR)	User akce v UI (mimo scope ADR-022, předpokládáno)	Stejné jako PATCH, jiný segment semveru	Stejné side effects
Publish triggered	`POST /api/v1/projects/{slug}/publish`	`projects.status := BUILDING`	Validace hosting kreditu, spuštění Kaniko buildu
Build + deploy success	Pipeline finish	`versions.published := true`, `versions.published_at := now()`, `projects.status := PUBLISHED`, `projects.prod_image_tag := <tag>`	`git tag vX.Y.Z`, SSE `publish.succeeded`
Build or deploy fail	Pipeline error	`projects.status := UPDATED` (nebo `DRAFT` pokud první publish), `versions.published` zůstává `false`	SSE `publish.failed`, error visible v UI
Republish older version	User vybere starší `Pending` nebo `RolledBack` verzi v dropdownu	Stejné jako standardní Publish	Tag idempotentně preserved (pokud již existuje a ukazuje na correct sha)

Versioning rules

Formát: MAJOR.MINOR.PATCH (semver 2.0.0 — bez pre-release/build metadata v alpha)
Initial: 0.1.0 při Create Project
PATCH bump: automatický, každý commit (user, Mara, Kai)
MINOR/MAJOR bump: manuální, user UI akce — předpokládáno (mimo scope B.7)
Bot bump commit: identifikován emailem bot@talkide.app + suffixem [skip-bump] v message; post-commit hook ho ignoruje (zamezení smyčky)
Unique constraint: (project_id, semver) v tabulce versions — duplicate semver rejected (DB integrity)
Versionovaná data: pouze user-app source code; TalkIDE BE má vlastní separate versioning (Spring Boot release tagy)

Business rules

Verze v Pending stavu jsou kandidáti pro Publish (UI dropdown default = nejnovější Pending).
RolledBack verze (= dříve published, nyní superseded) jsou v dropdownu taky selectable — selection = “publish this old version again” = klasický rollback flow.
Failed verze jsou v dropdownu skryté ve výchozím nastavení; user může toggle “Show failed” pro retry.
git tag vX.Y.Z je vytvořen pouze po úspěšném Publish (ne při bumpu). Tag je lightweight, lokální, žádný external push (ADR-013).
Tag pointuje na versions.sha = commit s funkčním kódem (před bump commitem [skip-bump]). Bump commit sám tagován není — viz ADR-022 sekce “Risks”.
Smazání projektu kaskádově maže všechny verze (DB CASCADE). PROD K8s resources se smažou separátním cleanup flow (mimo scope tohoto dokumentu).
Hosting billing stav (hosting_billing_account.status) je validován před přechodem Pending → Building. SUSPENDED účet → 402 HOSTING_BUDGET_EXCEEDED, verze zůstává v Pending. (⚠️ Pozn.: původní UserBudgetEntity.hostingCreditUsd prepaid check odstraněn v be#142 — hosting je výhradně postpaid, DP-7.)
Concurrent Publish ochrana: projects.status := BUILDING v transakci s podmínkou status IN (DRAFT, PUBLISHED, UPDATED) — second concurrent click vrátí 409.

Vztah k Project Management Flow

Project status	Povolené Version transitions
`DRAFT`	Bump (Pending vznik); Publish (Pending → Building)
`BUILDING`	Žádné Publish; bump je teoreticky možný, ale UI commit gesture je disabled během buildu
`PUBLISHED`	Bump (Pending vznik, status → UPDATED); Publish jiné verze (rollback flow)
`UPDATED`	Bump (Pending vznik); Publish (Pending → Building)
`PAUSED`	Žádný bump (commit gesture disabled), žádný Publish
`ARCHIVED`	Žádný bump, žádný Publish; verze v DB zachovány read-only

Was this page helpful?

Thanks for the feedback.