Docs

Turnstone

The facts Turnstone keeps

Each fact that Turnstone keeps about a bug, where Turnstone reads it from, and what Turnstone never stores.

View as Markdown

On this page
  1. Issues Turnstone reads
  2. Facts and sources
  3. What Turnstone never stores
  4. Bug record format

Turnstone keeps a fixed set of facts about each bug. This page lists each fact and the place that Turnstone reads it from.

Issues Turnstone reads

Turnstone reads only the issues that carry the testkit label. Each of those issues is one bug.

Facts and sources

FactSource
Issue number and linkThe provider. Turnstone keys a bug by its issue.
Open or closedThe issue's state.
Caught dateThe issue's creation time.
Fixed date and fixing commitThe issue's close time and the commit that closed it. An issue closed with no commit counts as closed, not as fixed.
SeverityThe severity:<level> label.
AreaThe area:<id> label. The label wins over the facts block. The area's name and its share of the code come from the facts block.
Cause, impact, how it was caught, test type, campaign, the commit it was found at, the introducing commitThe facts block in the issue body.
Introduced date, the change, and its kindTurnstone derives them from the introducing commit. The kind comes from the pull request's title prefix, such as feat: or fix:, or from its labels.

The severity levels are critical, high, medium, and low.

Turnstone keeps four more values from the facts block. Two of them are the finder's confidence in the cause and in the impact, each high or low. The third is the reason that the existing tests did not catch the bug. The fourth is the method that Testkit used to find the introducing commit.

People change severity and area by changing a label on the issue. A later sync reads the new label.

What Turnstone never stores

Turnstone stores no title, no issue text, no file path, no author, no test, and no evidence.

The facts block also names the test's file, the test's title, and the file that holds the fault. Turnstone does not keep those fields.

The issue stays with GitHub or Gitea, and the regression test stays in your repository. If Turnstone lost its data, you would lose your charts and nothing else.

Turnstone never writes to GitHub or Gitea.

Bug record format

The bug record format is the contract between Testkit and Turnstone. It defines the labels, the sections of the issue body, and every field of the facts block. The format is at version 1.

The Testkit package ships the format as a document. After you install Testkit, read this file:

node_modules/@gfdelarue/testkit/docs/bug-records.md

npx testkit bug guide prints the fields of a bug record and the lists of cause, impact, and escape ids.

  1. OverviewStartWhat Testkit is, and what you need to run it.
  2. Get startedStartFive steps from install to a merge gate.
  3. Test filesWrite testsWhere a test lives and what its name means.
  4. Contract testsWrite testsCall your running service from Node.
  5. HTTP testsWrite testsDrive routes with k6, signed in as named actors.
  6. Browser testsWrite testsAssert on a real page in Chromium.
  7. Database testsWrite testsRun SQL against a Postgres that Testkit builds.
  8. CIRunOne command decides whether a pull request merges.
  9. ResultsRunWhere a run's evidence lands and how to read it.
  10. CLIRunEvery command and flag.
  11. ConfigurationRunEvery field of testkit.config.ts.
  12. CampaignsHunt bugsGive your agent a target and collect proven bugs.
  13. Bug reportsHunt bugsThe five things every issue states.
  14. TurnstoneTurnstoneWhat the dashboard keeps, and what it never stores.
  15. Connect GitHubTurnstoneConnect a repository, and see the access Turnstone asks for.
  16. Connect GiteaTurnstoneAdd your Gitea host, then connect a repository.
  17. SyncTurnstoneWhen Turnstone reads your issues, and what it reads.
  18. FactsTurnstoneEach fact about a bug, and where Turnstone reads it.