Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Move plans out of the repository so a stale plan cannot be mistaken for how markfluence works

未关闭
  • 哪里不对？
#209 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

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

调研方向

Start by reviewing the 56 files under _plans/, the 38 citations across code, docs/root-model.md, docs/confluence/api.md, CLAUDE.md, and the README. Resolve the open questions about where plans belong and how existing plans should be migrated. Done means the agreed migration is complete, _plans/ is removed, references and workflow notes are updated, and needed reasoning remains in current documentation or comments.

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

描述

documentation

Problem

_plans/ holds 56 plans, 16.7k lines. Each is written once, at the moment an implementation starts, and deliberately never revised: _plans/README.md says a plan "describes what was intended at the moment it was written" and is "not documentation". But decisions get rethought after a plan lands, and the plan keeps saying the old thing.

That warning lives in one README that nobody passes through. Someone who greps for a function, a field or a flag lands directly on a plan, which is the most detailed and confident text in the repository about that thing, and can come away with the wrong understanding of how it is implemented. Two recent examples of plans drifting:

  • _plans/053 (update moves pages) planned a loop check through v2's ancestors route; the implementation found that route needs a scope nothing else uses and walks parent links instead.
  • _plans/055 (raw tables) was amended five times during implementation, including a measured correction of how a cell's alignment works.

Both record their amendments, but only at the end, after the original decisions a reader meets first. Claude Code reads the repository the same way a person does, and treats a plan as authoritative.

The repository also sends readers there on purpose: 38 citations of _plans/NNN in 23 files, including code comments, docs/root-model.md, docs/confluence/api.md and CLAUDE.md. 28 commit messages cite plans too.

Possible solution

Keep plans, but out of the repository, attached to the discussion they came from:

  • A plan is a comment on the issue it answers, posted before implementation starts. It is dated and sits beside the discussion that produced it, so it reads as history, because an issue is history. Work without an issue gets one first.
  • Amendments go in the PR description ("amended during implementation"), where review already happens, rather than into an edited plan.
  • Current behaviour stays where it is: markfluence CMD --help, docs/, and CLAUDE.md. Reasoning the code depends on belongs in a code comment or in docs/, not in a plan.

Migrating the existing plans:

  1. 37 of the 55 plans name the issue they answer. Post a comment on each of those issues linking to the plan at the last commit that has it (a permalink, rather than pasting 16k lines into issues; every plan would fit in a comment if pasting turns out to be better). The other 18 remain in git history.
  2. Replace each _plans/NNN citation in code, docs and CLAUDE.md with the issue number. Where a comment leans on the plan for reasoning it does not state itself, move that reasoning into the comment or docs/ first.
  3. Delete _plans/, and update the workflow notes in CLAUDE.md and the README's link.

Commit messages that cite _plans/NNN keep working: git show <commit>:_plans/NNN_… still finds the file at that commit.

Open questions

  • Permalink or pasted text for the existing plans?
  • Is an issue comment the right home, or would the PR description, a GitHub Discussion, or the wiki serve better?
主要语言
Go
星标
2
派生
0
平均合并
2 小时 31 分钟
30 天内合并 PR
59

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

mozilla/markfluence 的其他 Issue

查看 mozilla/markfluence 的全部 Issue

相似的 Issue

更多 Go Issue

把新 issue 发到你的邮箱

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