Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

Restructure ADRs into short decision records

Ouverte
  • Quelque chose ne va pas ?
#3,744 6 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
12/100
Type d'issue
Documentation
Clarté
Plutôt claire
Activité
Active
Stack technique
typescript
Domaine
documentation

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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.
Langage dominant
TypeScript
Étoiles
5.1k
Forks
339
Merge moyen
12 h 50 min
PR mergées (30 j)
632

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de callstack/agent-device

Toutes les issues de callstack/agent-device

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.