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

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

Aperta
  • Qualcosa non va?
#209 0 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
25/100
Tipo di issue
Refactoring
Chiarezza
Da chiarire
Stato di attività
Attiva
Stack tecnologico
github
Ambito
developer-experience, documentation

Direzione di ricerca

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.

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

Descrizione

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?
Lingua principale
Go
Stelle
2
Fork
0
Merge medio
2h 29m
PR unite (30g)
60

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 mozilla/markfluence

Tutte le issue di mozilla/markfluence

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.