design: extend the single source of record to fields: what each action reads, writes, and shows, per forge #517

New issue

Open

opened 2026-09-15 23:09:43 +00:00 by hexajon · 0 comments

hexajon commented

2026-09-15 23:09:43 +00:00

Owner

What happens

ADR 0008 gives help text and parameter names one source of record, and ADR 0014 gives behavior one service layer. Neither covers the data: which fields an action reads, writes, and shows, and what each forge calls them. Those are hand-written per struct and per formatter, so they drift:

repos get does not show merge settings, features, or the website, though repos edit sets them, and the raw_json description says the text shows the full content.
actions runs reads Gitea's field names only, so Forgejo runs show no branch or start time (#504).

Ask

A new decision record (created with adr new) that sets the single source for fields, and the checks that follow from it. Options to weigh:

Struct tags as the source. Each service type declares, per field, its JSON name for Gitea and for Forgejo, whether edit can set it, and whether get shows it (for example a madtea:"settable,shown,group=merge" tag). edit parameters and get output both derive from the tags. Tests use reflect to check that every settable field is shown and every field maps on both forges. This is the encoding/json approach.
Field entries in opspec, next to the operation specs from ADR 0008.
Generated types from the vendored API specs (docs/api-specs/) with go generate, with a hand-written mapping layer for the two forges.

Whatever is chosen, add:

a test that every field edit can set appears in get, for every noun,
a forge-shape test that decodes fixtures in the shape of each vendored spec and fails on an unmapped field the text output needs.

Open question

Which option.

Acceptance

The decision record exists.
Both tests run in the gate, and the drift in #504 and in repos get shows up as a failing test before its fix.

## What happens ADR 0008 gives help text and parameter names one source of record, and ADR 0014 gives behavior one service layer. Neither covers the data: which fields an action reads, writes, and shows, and what each forge calls them. Those are hand-written per struct and per formatter, so they drift: - `repos get` does not show merge settings, features, or the website, though `repos edit` sets them, and the `raw_json` description says the text shows the full content. - `actions runs` reads Gitea's field names only, so Forgejo runs show no branch or start time (#504). ## Ask A new decision record (created with `adr new`) that sets the single source for fields, and the checks that follow from it. Options to weigh: 1. **Struct tags as the source.** Each service type declares, per field, its JSON name for Gitea and for Forgejo, whether `edit` can set it, and whether `get` shows it (for example a `madtea:"settable,shown,group=merge"` tag). `edit` parameters and `get` output both derive from the tags. Tests use `reflect` to check that every settable field is shown and every field maps on both forges. This is the `encoding/json` approach. 2. **Field entries in `opspec`**, next to the operation specs from ADR 0008. 3. **Generated types** from the vendored API specs (`docs/api-specs/`) with `go generate`, with a hand-written mapping layer for the two forges. Whatever is chosen, add: - a test that every field `edit` can set appears in `get`, for every noun, - a forge-shape test that decodes fixtures in the shape of each vendored spec and fails on an unmapped field the text output needs. ## Open question Which option. ## Acceptance - The decision record exists. - Both tests run in the gate, and the drift in #504 and in `repos get` shows up as a failing test before its fix.

hexajon added the

enhancement

status/needs-decision

labels

2026-09-15 23:09:43 +00:00

hexajon referenced this issue

2026-09-15 23:09:55 +00:00

Epic: accepted decisions are enforced by checks, not only recorded #518

hexajon added a new dependency

2026-09-15 23:09:59 +00:00

#518 Epic: accepted decisions are enforced by checks, not only recorded