Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#209 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Refactorización
Claridad
Necesita aclaración
Estado de actividad
Activo
Stack tecnológico
github
Área
developer-experience, documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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?
Lenguaje dominante
Go
Estrellas
2
Forks
0
Merge medio
2 h 31 min
PR fusionados (30 d)
59

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de mozilla/markfluence

Todos los issues de mozilla/markfluence

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.