VCS activity timeline
patterns specs/patterns/vcs-activity-timeline.kmd
The chronological event stream on a code-hosting issue or pull request: comments interleaved with typed activity events (committed, labeled, assigned, referenced, closed, merged, reviewed), each with a semantic event icon/color, actor avatar, and relative timestamp. Modeled after the GitHub issue/PR timeline (Primer). Used by Koder Flow.
Quando este padrão se aplica
Triggers primários
- Build the issue/PR timeline for a code-hosting product
Todos os triggers
- Render the activity history of an issue or pull request
- Interleave comments with typed events (commit, label, close, merge)
- Show who did what, when, on a code-hosting entity
Corpo da especificação
Pattern — VCS activity timeline
Status: v0.1.0 — Draft. Promoted from the GitHub Primer parity scan (meta/docs/stack #092). Source: GitHub issue/PR timeline.
R1 — Two row kinds
- Comment rows: a full comment card (avatar, author, timestamp, markdown body, reactions/actions). Visually weighty.
- Event rows: a compact single line (icon + actor + verb + object + time), e.g. "● merged commit a1b2c3d into main". Visually light.
Both share the same left rail so the stream reads as one column.
R2 — Event types (typed, semantic)
Each event type has a fixed icon + semantic color, so the stream is scannable by event:
| Event | Icon | Semantic color |
|---|---|---|
| committed / pushed | commit | neutral |
| labeled / unlabeled | tag | the label's color |
| assigned | person | neutral |
| referenced / cross-ref | link | neutral |
| renamed / edited | pencil | neutral |
| closed (issue) | issue-closed | done/neutral |
| reopened | dot | success |
| merged (PR) | git-merge | done (purple) |
| closed unmerged (PR) | pr-closed | danger |
| review (approved / changes) | check / diff | success / danger |
Color is never the only signal — icon + verb text always render (WCAG
1.4.1). The PR/issue state shown alongside reuses
specs/components/state-label.kmd.
R3 — Actor & timestamp
- Each row shows the actor avatar + name (the actor is a link to the profile).
- Timestamps render relative ("3 days ago") with the absolute
date/time in the
title/tooltip and as machine-readabledatetime. - Relative time updates are tolerant (no per-second churn); formatting is locale-aware (R6).
R4 — Ordering, grouping & loading
- Strictly chronological (oldest→newest), newest at the bottom near the composer.
- Consecutive same-actor same-type events MAY collapse into one grouped row ("X added 3 commits") that expands on demand.
- Long timelines paginate/virtualize; while loading, rows use
specs/components/skeleton.kmd. Any hidden/older range is disclosed (no silent truncation).
R5 — Commit parent graph (PR)
For a PR's commit events, an optional compact lane visualizes the parent/branch graph (merge vs linear). The graph is decorative augmentation of the textual list, never the sole carrier of the commit relationship.
R6 — Accessibility & i18n
- The timeline is an ordered list; each row is reachable and announces actor + verb + object + time.
- Avatars are decorative when the actor name is adjacent (
alt=""), else carry the actor name. - Verbs, grouped-count strings, and relative-time formatting are localized
per
specs/i18n/contract.kmd(ICU plural for "{n} commits"); user content (comment bodies) is never machine-translated.
Não-escopo
- The comment composer + comment card internals (separate component).
- Reactions (separate follow-up).
- The diff / review surfaces (
specs/components/diff-viewer.kmd,specs/patterns/code-review.kmd). - Event production / storage (Koder Flow backend).
Referências
specs/components/state-label.kmdspecs/components/lists.kmdspecs/components/skeleton.kmdspecs/i18n/contract.kmd