Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Restructure ADRs into short decision records

Aperta
  • Qualcosa non va?
#3,744 6 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
12/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
documentation

Direzione di ricerca

Start with the ADRs in docs/adr/ and the AGENTS.md routes that point to them, then find the agent-guidance test that sets byte budgets. The work is a classification pass: for each ADR, decide keep, merge, move to evidence, or convert to an issue, and record a migration ledger. Done means docs/adr/FORMAT.md exists with its own budget, the routes are split, and the size gate passes at about 8 KB per ADR. Because this is blocked by #3729 and #3731, it is not a good first task.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation

Purpose

ADRs must record decisions, not implementations. Today docs/adr/ has 33 ADRs and 689 KB. Several ADRs are 40–94 KB and mix the decision with file maps, measurements, rollout plans, and amendment history. Contributors and agents cannot find the current decision quickly, and the implementation detail gets stale.

Required behavior

  • Add docs/adr/FORMAT.md with the authoring rules. Give it its own byte budget in the agent-guidance test.
  • Split the AGENTS.md route: "Read architecture decisions" goes to docs/adr/README.md. "Write or amend an ADR" goes to docs/adr/FORMAT.md.
  • Write an ADR only if the decision is hard to reverse, surprising without context, and the result of a real trade-off.
  • An ADR contains the decision (API, data flow, invariants, constraints, boundaries), why, the rejected alternatives with reasons, and the consequences and open gaps. Exact names (commands, wire fields, typed reasons) stay when they explain the decision.
  • An ADR does not contain implementation inventories, measurements, rollout or migration plans, PR logs, or status change-logs. Each moves to its owner: registries, types, and gates; package docs and help; docs/evidence/; or an umbrella issue.
  • An ADR is a living record. The decision states the current truth. An optional dated "Decision history" line records a real change of direction, with its reason and a link. A new ADR is written only when the problem or the scope changes.
  • Proposals live in umbrella issues. An ADR is written when a decision is accepted.

Completion conditions

  • Each ADR has one classification: keep, merge, move to evidence, or convert to an issue.
  • Each kept decision is checked against the code. If the code changed for a good reason, the ADR states the new decision and its reason. If the code drifted by mistake, an issue records it.
  • Each PR has a migration ledger: old section → kept, moved to a named owner, or deleted with a reason.
  • Each PR updates the code comments that cite the ADR sections that it changes.
  • A size gate (about 8 KB for each ADR) runs last, with no allowlist.

Dependencies

  • Blocked by #3729, #3731, and the stale-facts PR that stacks on them.
Lingua principale
TypeScript
Stelle
5.1k
Fork
339
Merge medio
12h 57m
PR unite (30g)
653

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di callstack/agent-device

Tutte le issue di callstack/agent-device

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.