mozilla / mozilla/markfluence

export: --clean, for re-exporting a tree whose pages were deleted upstream

Open
#129 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
2
Forks
0
Avg merge
2h 8m
Merged PRs (30d)
49

Description

Deferred from #59, which shipped export --depth/--space.

Re-exporting a tree into a destination that already has one leaves behind a file for every page that has since been deleted, moved out of the subtree, or renamed — a rename changes the slug, so the old file stays and a new one appears beside it. Nothing reports this: the export succeeds, and the stale file looks exactly like a page that was skipped because it was already there. Someone reading the tree, or publishing it back with create, has no way to tell.

--clean would remove what the export did not write. That is removal, so it is bound by the three safety guarantees in docs/guarantees.md that are currently all Vacuous — nothing in markfluence removes anything today, so this would be the first thing to exercise them:

  • S4 (no-removal-as-side-effect) — removal has to be the command's stated purpose. So a flag, never implied by --force.
  • S5 (remove-only-ours) — only what markfluence created. A tree exported into a directory that also holds hand-written notes must not lose them, and an export knows exactly which paths it wrote, so the rule is expressible.
  • S6 (removal-is-previewable) — it says what it will remove before doing it, and honours --dry-run.

Making those three non-vacuous is most of the work here, and it wants its own spec rather than a flag bolted onto the export loop.

Some questions that spec would need to answer:

  • What counts as "ours"? The paths this run wrote is the easy half. The hard half is a file from a previous export of the same tree, which this run did not write and cannot distinguish from something a human added — unless the export records a manifest, which is state on disk that everything else in markfluence has so far avoided.
  • Attachments too, or only page files? An attachment whose page was deleted is as stale as the page, but a recorded path= can point anywhere under the destination, including at a shared asset another page still references.
  • What about a partial run? A walk that failed halfway, or a page that failed to export, means "not written by this run" does not mean "gone upstream". Cleaning after anything less than a complete successful export would delete live content.

That last one may be the deciding constraint: --clean might only be safe when the run exported everything it walked, with no failures.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/guarantees.md and the export, create, --force, and --dry-run behavior described in the issue. Define the spec for S4–S6, including ownership of prior exports, attachments, manifests, and partial runs; done means a decided, previewable cleanup design that cannot remove unrelated or potentially live content.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.