Initiatives

Initiatives track long-running codebase improvements as engineer-defined numeric counts. You decide what one item means. Dev Herald stores each count against the commit it was measured on and shows how it changes.

What to count

Each initiative has one or more metrics. A metric is a named count with a label, an optional unit, a target, and a direction (lower or higher is better).

Two counts cover most migrations:

Affected files — how widely the remaining work is spread. A file with 40 legacy usages and a file with one usage each count as one file.
Remaining occurrences — how many individual things still need changing, such as legacy component usages, API calls, or @ts-ignore directives.

Other counts use the same fields. Skipped tests, or workspaces still on an old build, are just another named count. They are not separate product features.

Remaining work is the default story. A metric that aims down toward zero is shown as 412 → 388 occurrences remaining and 24 removed. Dev Herald does not show a percentage of the migration completed, because the size of the repository can change.

Create an initiative

Open a project in the dashboard and choose Initiatives. Give it a name and a slug. The slug is what your measurement request uses, and it stays fixed once the first snapshot exists.

Example metrics for moving off Emotion:

Label	Key	Unit	Target	Direction
Affected files	`files`	files	0	Lower is better
Remaining occurrences	`usages`	occurrences	0	Lower is better

Send a measurement

POST /api/v1/initiatives/measurements with the project API key.

The body is the commit, the time, and slug-keyed counts. Every metric key defined on a named initiative must be present. Initiatives you omit are left unchanged. Sending the same commit again replaces that snapshot. The request body is not stored as a file.


curl -X POST https://dev-herald.com/api/v1/initiatives/measurements \
  -H "Authorization: Bearer $DEV_HERALD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "2026-04-02T12:00:00.000Z",
    "commitSha": "abc123def4567890",
    "initiatives": {
      "emotion-to-panda": { "files": 12, "usages": 96 }
    }
  }'

Unknown slugs, unknown metric keys, and archived initiatives fail the request.

Official history is these default-branch snapshots. The progress page charts each metric and draws the target. Health Reports include the latest snapshot at or before that report, with a link to the progress page.

Your script decides how to count. Dev Herald only stores and compares the numbers.