Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Restructure ADRs into short decision records

Đang mở
  • Có gì không ổn?
#3,744 6 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
12/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
typescript
Lĩnh vực
documentation

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
TypeScript
Star
5.1k
Fork
339
Merge trung bình
12 giờ 50 phút
Pull request đã merge (30 ngày)
632

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của callstack/agent-device

Tất cả issue của callstack/agent-device

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.