akiomik / akiomik/tears

Prose in one file pins code in another, and nothing brings the change back to it

未关闭
#363 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
documentation
主要语言
Rust
星标
9
派生
1
平均合并
11 小时 46 分钟
30 天内合并 PR
62

描述

## Summary

Prose in one file describes code in another, and nothing brings the person
changing that code back to it. #362 adds an obligation covering a file's own
documentation and deliberately stops there, because the search that finds the
cross-file case is one I could not state correctly — two attempts in that PR
were both wrong.

## Where it already bites

`docs/testing.md` is the largest instance in the tree. Its tracing sections name
`src/runtime/load.rs`, `src/runtime/channel.rs`, `src/kernel/producer.rs`,
`src/kernel/conformance/quit.rs` and `tests/observability.rs`, and pin exact
values from them — an emission sequence of `[3, 2, 1, 0]`, a positional read of
`ids[0]` against `ids[2]`. None of those files points back.

The same document says so about itself: its note that `u64_values(...).last()`
does not compile is followed by "An edit that added `last()` to `Readings` would
pass the whole run. … review is what holds them."

## What is known

`docs/rfcs/pre-review-checklist.md` has worked part of this out for RFC review,
and its entries record what does *not* find a stale restatement: a stale one
rarely shares vocabulary with the sentence that made it stale, so a search for
the changed sentence, or for a renamed identifier, goes straight past it. What
found them in PR #240 and PR #246 was the claim's subject vocabulary and the
concept removed.

That method is written for someone revising a contract document, not for someone
changing a runtime and unaware that any prose depends on it.

## What would close this

Something the person changing the code can act on without already knowing which
documents describe it. Options worth weighing rather than a decided design:

- a check that fails when prose names an item that no longer exists — the tree
has no link checker for Markdown, and 563 intra-doc links in `src/` show the
same idea works where rustdoc can see it
- a convention that prose naming an item from another file names it in a form
something resolves
- accepting review as the mechanism, and saying so in the document rather than
leaving it implied

## Acceptance criteria

- [ ] A contributor changing code in `src/` can find out whether prose elsewhere
depends on it, without knowing in advance that it does.
- [ ] Whatever is chosen is recorded where a contributor will meet it, not only
in a pull request.

贡献指南

打开贡献指南

调研方向

Start with docs/rfcs/pre-review-checklist.md and inspect the cross-file examples in docs/testing.md, including the referenced src/ and tests/ files. Review PRs #240, #246, and #362 for prior constraints and approaches. Done means a contributor changing src/ can discover dependent prose without prior knowledge, and the chosen practice is recorded where contributors will encounter it.

由索引模型根据 Issue 内容生成。

评估

技术栈
rust
领域
developer-experience, documentation
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
活跃
描述清晰度
需要澄清
新手友好度
30/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。