werkator/docs/prs/2026-10-14-PR#160-home-builds-panel.md

PR#160: The home page lists running, queued and failed builds, and its tiles are smaller

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

Problem

The home page has two panels: System and Repositories. A repository card shows only its newest build and counts the running and failed ones. To see which builds run, which wait and which failed, a reader has to open each repository's views. Also, only three cards fit in one row on a desktop screen, so the mosaic grows tall quickly.

Non-Goals

• No live log on the home page: a tile leads to the Current Builds view for that.
• No change to the repository cards' tags and tints: they keep counting as before.
• No build-definition key, so ADR 0010 is not touched.
• No new layout of the other pages: they only get wider.

Specification

Feature: the Builds panel on the home page

Background

• A run's name is its pool, <branch> or <branch>@<build>: one build definition on one branch.
• A failure is a run that ended failed or timed_out.
• A failure is outdated when its branch is gone or a newer run of its name ended with a verdict (PR#156).

Scenario#160.01: The panel shows the running builds first, then the queued ones, then the failures, at most five!

So that what happens now comes before what waits, and what waits before what is broken.

• Given running, queued and failed builds in several repositories
• When the home page shows the Builds panel
• Then the running builds come first, the one running longest first
  • and then the queued builds, the one waiting longest first
  • and then the failures, the newest first
  • and the panel shows at most five builds

Verified by

• BuildActivityUnitTest: running builds come first, then the queued ones, then the failures, at most five

Scenario#160.02: A failure whose name runs or waits again has no tile!

So that the panel does not show a failure twice, once as red and once as the build that answers it.

• Given a failure of a name
• When a newer run of the same name is running or queued
• Then the panel shows the newer run
  • and not the failure

Verified by

• BuildActivityUnitTest: a failure whose build definition runs or waits again has no tile of its own

Scenario#160.03: An outdated failure has no tile!

So that the panel shows only failures that still say how a branch stands.

• Given a failure
• When its branch is gone, or a newer run of its name ended with a verdict
• Then the failure has no tile

Verified by

• BuildActivityUnitTest: an outdated failure has no tile

Scenario#160.04: A failure older than seven days has no tile!

So that the panel counts failures like the "failed" tag of the repository cards.

• Given a current failure
• When it started more than seven days ago
• Then it has no tile

Verified by

• BuildActivityUnitTest: a failure older than seven days has no tile

Scenario#160.05: A failure followed only by a cancelled run keeps its tile!

So that cancelling a rebuild does not hide a failure nobody answered.

• Given a failure of a name
• When the only newer run of that name was cancelled
• Then the failure keeps its tile

Verified by

• BuildActivityUnitTest: a failure followed only by a cancelled run keeps its tile

Scenario#160.06: A visitor sees a private repository's build counted and timed, but not named!

So that the panel keeps RFC 0003, D8: metadata for everyone, content only with the control token.

• Given a running build of a private repository
• When a visitor without the control token reads the home page or GET /api/activity
• Then the tile keeps the status and the times
  • and the repository, the build name, the commit and the pull request are replaced
  • and the tile leads nowhere

Verified by

• BuildActivityUnitTest: a visitor sees a private repository's build counted and timed, but not named
• ReposApiControllerRestTest: GET /api/activity answers the Builds panel's tiles as asked for by a visitor without the token
• UiHomeRestTest: a private build's tile is anonymous and leads nowhere

Scenario#160.07: The Builds panel stands above the Repositories panel!

So that the reader sees what happens before what each repository did last.

• Given builds for the panel
• When the home page renders
• Then the Builds panel stands above the Repositories panel
  • and it shows one tile per build, in the order of the list

Verified by

• UiHomeRestTest: the Builds panel stands above the Repositories, one tile per build

Scenario#160.08: A tile names the repository, the build and its commit!

So that a reader knows what a tile is about without opening it.

• Given a build of the panel
• When the home page renders its tile, first by the server and then by every poll
• Then the tile shows the repository, the status, the build name, its pull request, its commit and its start

Verified by

• UiViewsUnitTest: a build tile names the repository, the build, its commit and its timing

Scenario#160.09: A tile is tinted by its status!

So that what needs attention stands out, like on the repository cards.

• Given a build of the panel
• When the home page renders its tile
• Then a running tile is blue, a failed or timed-out one red, a queued one calm, a private one grey

Verified by

• UiViewsUnitTest: a build tile's tint

Scenario#160.10: The time of a running or queued build counts on!

So that the tile shows how long a build runs or waits without a new poll.

• Given a running or queued build of the panel
• When the home page shows its tile
• Then its time counts every second, a queued one italic

Verified by

• UiHomeRestTest: a running or queued tile carries what the ticker counts from, a queued one italic
• UiViewsUnitTest: a build tile names the repository, the build, its commit and its timing

Scenario#160.11: A tile leads to where its build can be followed!

So that one click shows the live log of a running build, or the log of a failed one.

• Given a build of the panel
• When the reader clicks its tile
• Then a running or queued build leads to its repository's Current Builds view
  • and a failure leads to its build page

Verified by

• BuildActivityUnitTest: a running build leads to its repository's Current Builds view, a failure to its build page
• UiHomeRestTest: a tile links where the list says

Scenario#160.12: An empty Builds panel says so!

So that a quiet instance does not look like a broken page.

• Given no running, queued or current failed build
• When the home page renders
• Then the Builds panel says that nothing is running, queued or failed this week

Verified by

• UiHomeRestTest: an empty Builds panel says so

Feature: five tiles per row

Scenario#160.13: Five tiles fit in one row on a desktop screen!

So that the five builds of the panel are one row, and the mosaic stays short.

• Given a browser window of 1366 px or more
• When the home page shows the Builds panel and the Repositories panel
• Then each panel puts five tiles in one row

Verified by

• Manual check on a demo instance with three repositories: five columns of 181 px at 1366 px, five of 208 px at 1920 px, one column and no sideways scrolling at 375 px.

Scenario#160.14: Every page has the same, larger width!

So that header and content do not jump when the reader goes from the home page to another page.

• Given any page of the instance
• When the browser window is wider than 1504 px
• Then the header, the content and the footer are 1440 px wide instead of 1180 px

Verified by

• Manual check on the demo instance: header and content 1302 px wide at 1366 px; the stylesheet sets one min(1440px, …) for all of them.

Solution

• BuildActivity collects the panel's builds on read from each repository's history: running and queued runs, and the failures that are not outdated (OutdatedRuns, PR#156), are of the last seven days (RepoOverviews.RECENT_FAILURE_WINDOW) and have no running or queued run of their name. It sorts and cuts to five over all repositories, so the first five are the most urgent of the instance, not of one repository.
• OutdatedRuns.PROBLEMS is public now, so both use the same set of failures.
• GET /api/activity serves the list; Redaction.redact(ActivityBuildDto) redacts a private repository's tile for a visitor.
• HomeBuildView is the tile for the server's first paint; renderHomeBuild in werkator.js renders the same markup on every poll. The tile carries the data attributes of the existing ticker (tickRunningDurations), so a running or queued time counts every second without a new mechanism. The card's head and middle line are shared helpers in werkator.js now (homeCardHead, homeCardMid).
• home.html puts both panels into one main.home-main column.
• CSS: every page is min(1440px, …) wide, the home grid's tiles are at least 180 px instead of 250 px, and the cards' padding and fonts are a little smaller to fit.
• Werkbaum: a node under #ui.
• Version 1.43.0, with an entry in the release notes.

Additional Changes

• The architecture skill describes the panel.
• A private repository's card on the home page no longer has an empty href, which led to the home page itself until the first poll. th:href with a null value wrote the attribute empty; th:attrappend leaves it out. UiHomeRestTest: a private repository is a card without a destination checks it now.