Read the programmes' history¶
Nerthus.Platform and Nerthus.Config are built as two programmes of sprints, each cut into
session-sized tasks. Every task lands as one merge request with one merge commit, so main in each
repository is a list of tasks. This page is how to read that list back, in either repository and in
the repositories both programmes touch (Nerthus.Infra, Nerthus.Docs, and each other's).
Where a task id lives¶
In a trailer, never in the subject:
feat(secrets): refuse a vault credential with no ceiling
A credential an issuer minted for the estate had no upper bound on its life.
Task: P01-08
Co-Authored-By: …
The subject keeps the regime's grammar (<type>(<scope>): <summary>, 72 characters). The body is
optional and short: at most ten lines, what and why as of now. The id is a trailer so that neither
rule has to give way to the other.
The merge request title starts with the id: P01-08: <task title>, C02-03: <task title>.
Branch names¶
| Namespace | Programme | Who writes it |
|---|---|---|
proj/<nn>-<mm>-<slug> |
Platform | a task; the slug is the task file's stem |
fix/, ci/, docs/<nn>-<mm>-<slug> |
Platform | a follow-up on a landed task, keeping its id |
proj/<nn>-99-sweep |
Platform | the sprint sweep |
conf/<nn>-<mm>-<slug> |
Config | a task |
conf-fix/, conf-ci/, conf-docs/<nn>-<mm>-<slug> |
Config | a follow-up on a landed task |
conf/<nn>-99-sweep |
Config | the sprint sweep |
feat/, chores/<slug> |
either | work with no task; rare, and it carries no trailer |
apply/<utc>, import/<utc>, drift/<utc> |
Config's tool | written by nerthus-config alone, in Nerthus.Infra |
vm/, lang/, deploy/ |
machines | nobody writes one by hand |
A task that spans repositories uses the same branch name in each of them. A Platform task that
cuts a release Config depends on lands its Config merge request on its own proj/ branch with its
own Task: P… trailer, and the reverse holds for Config tasks in Platform.
The recipes¶
| Question | Command |
|---|---|
| What did Platform sprint n land? | git log --merges sprint/<n-1>..sprint/<n> |
| What did Platform's first sprint land? | git log --merges sprint/01 |
| What did Config sprint n land? | git log --merges config-sprint/<n-1>..config-sprint/<n> |
| What did Config's first sprint land? | git log --merges config-sprint/00 |
| Every commit of one task | git log --grep='^Task: P01-06' |
| That task's one merge node | git log --merges --grep='P01-06:' |
| The whole programme, one line per task | git log --merges --format='%h %s' main |
| Which task does this commit belong to? | git log -1 --format='%(trailers:key=Task,valueonly)' <sha> |
| Every commit with its task, both programmes | git log --format='%(trailers:key=Task,valueonly) %s' |
--grep reads the whole message, which is why the recipes anchor the trailer with ^Task:: a body
that mentions another task in prose is not a commit belonging to it. The programme letter (P or
C) is what separates the two programmes in a repository both touch.
sprint/01 is Platform's first tag and covers its first two stages; config-sprint/00 is
Config's. Commits from before the trailer rule carry no Task: trailer and are not rewritten: the
sprint tag and the merge request titles are how those tasks are found.
The tags¶
| Tag | What it marks |
|---|---|
sprint/<nn> |
Platform's sweep merge commit; the message lists the sprint's tasks with their merge commits |
config-sprint/<nn> |
the same, for Config |
vX.Y.Z |
a release of the repository's package; the only tag that runs a pipeline |
archive/<date>/<slug> |
a branch preserved before deletion |
A sprint tag or an archive tag runs no pipeline: neither publishes anything, and a release job asked to judge one would refuse it as not a release.
What the gates check¶
Every merge request in Platform and in Config runs ci/gates.py task-trailer; Nerthus.Infra runs
the same rules as nerthus-config gates regime. On a branch whose name carries a task id:
- every commit in the merge request carries
Task:equal to the branch's id. A commit with no trailer and a commit with another task's trailer are separate findings: one is a session that forgot, the other a commit on the wrong branch; - the merge request title starts with the id and a colon;
- a body over ten lines is a warning, not a refusal.
A branch with no task id (feat/, chores/, the machine namespaces) is told the rules do not
apply. Merge commits are exempt: GitLab writes them.