IF Commons GitHub

lens/repo-ops

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-docs FR-029

The Repo Ops lens (commons 0001-docs FR-029): the section that says how a repository is operated. Its pages are written by people in Markdown, beside the code, and say what a reader needs once; the lens appends to a page what can be read from the repository's own typed facts, so that it stays true: the workflows (from the typed definitions their files are made from), the commands of the operations program (from its verb definitions, with each one's options and examples) and the facts of the release. It knows nothing of the repository's tools: what it shows is given to it as values, and a page that links elsewhere in the site does so by a Markdown link.

A page names the file it is written in, its address and its order; generated says which typed facts follow its words. A page that cannot be read is a finding and the others are made. The section is in the top bar when it has a page.

import { repoOpsLens } from "@intellectual-frontiers/docs/lens/repo-ops";
repoOpsLens({ name: "repo-ops", pages: [{ file: "guides/ops-index.md", path: "repo-ops/index.html", order: 0 }] });

Source: commons/docs/src/lens/repo-ops.ts

1 of 8 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

OpsWorkflowinterfaceno test imports it
interface OpsWorkflow

One workflow, as the typed definitions say it.

MemberTypeWhat it is
filestringIts file, from the repository's root.
namestringIts name.
triggersreadonly string[]What starts it: push, pull_request, workflow_dispatch, schedule: 0 * * * *.
jobsreadonly { readonly id: string; readonly name?: string | undefined; }[]Its jobs, by id (the name of a job in a matrix is an expression, and the id is what a person looks for).
purposestringWhat it is for, in a sentence.
OpsVerbinterfaceno test imports it
interface OpsVerb

One verb of the operations program, as its own definition says it.

MemberTypeWhat it is
wordsstringThe words a person types after the command: release plan.
summarystring
effectstringread, mutate or destructive.
tierstringThe lowest tier that sees it.
idempotentboolean
dryRunbooleanWhether --dry-run previews it.
checkbooleanWhether --check ends with findings where it would change something.
optionsreadonly { readonly name: string; readonly meaning: string; }[]The options with what each means.
examplesreadonly string[]Command lines with a comment, as the program gives them.
page?stringThe page that documents the verb in full, where the site has one.
OpsFactinterfaceno test imports it
interface OpsFact

One fact the page of the release states.

MemberTypeWhat it is
labelstring
valuestring
OpsGeneratedtypeno test imports it
type OpsGenerated = "workflows" | "verbs" | "facts" | "policy";

What follows a page's words.

RepoOpsPageinterfaceno test imports it
interface RepoOpsPage

One page of the section: the Markdown file, its address and what is generated after it.

MemberTypeWhat it is
filestringThe Markdown file, from the repository's root. Its first heading is the page's title.
pathstringThe page's address on the site, as repo-ops/ci-cd.html.
ordernumberIts place in the section, lowest first.
generated?readonly OpsGenerated[] | OpsGeneratedThe typed facts that follow its words (one kind, or several in order).
OpsPolicyinterfaceno test imports it
interface OpsPolicy

The build policy as the typed values of the workflows say it (commons 0038-build-policy): the red causes with their reasons, the release policy, and the classification of every step.

MemberTypeWhat it is
redCausesreadonly { readonly cause: string; readonly why: string; }[]
release{ readonly mode: string; readonly until: string; }
countsReadonly<Record<string, number>>
stepsreadonly { readonly file: string; readonly job: string; readonly step: string; readonly policy: string; readonly detail: string; readonly why: string; }[]
RepoOpsOptionsinterfaceno test imports it
interface RepoOpsOptions

What the Repo Ops lens is given.

MemberTypeWhat it is
namestringIts name, which the build reports it by.
pagesreadonly RepoOpsPage[]The pages.
workflows?(() => readonly OpsWorkflow[])The workflows.
verbs?(() => readonly OpsVerb[])The verbs of the operations program.
facts?(() => readonly OpsFact[])The facts of the release.
policy?(() => OpsPolicy)The build policy and the classification of every step.
command?stringThe command the verbs are run with (repoctl), for the usage lines.
repoOpsLensfunction
function repoOpsLens(options: RepoOpsOptions): Lens

The Repo Ops lens.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.