docs: point at markfluence-action and delete the CI document - #182
Merged
Merged
Conversation
mozilla/markfluence-action holds it now (#29). The design in _plans/047 transferred intact -- the findings, the phases and the constraints are all unchanged -- so this records where the code went and why, rather than rewriting the plan. The reason is release cadence. In this repository the action's releases are welded to the CLI's: a one-line fix to the installer could not reach anyone until a whole markfluence release was cut, which is backwards, since the action changes most in its first months and the CLI is the stable half. A separate repository also lets the action be v1 immediately instead of waiting for markfluence 1.0.0 to make `uses: ...@v1` meaningful. The alternative was a second tag prefix like action-v1.0.0 here, which is two tag namespaces in one repository -- worse than two repositories. Split at zero consumers, which is the cheapest it will ever be. The cost is recorded rather than glossed: coordinated changes are now two pull requests with nothing linking them, where dropping Intel macOS (#180) was one commit and one CI run. CLAUDE.md names the three things over here the action depends on -- the archive naming from goreleaser's name_template, the platform set, and release.draft plus prerelease: auto keeping /releases/latest trustworthy -- because nothing in `make check` will catch a mismatch.
7 tasks
Code review of the move found four ways the previous commit's warning failed to do its job. **The list was incomplete in exactly the way it existed to prevent.** It named three couplings; there are five. The action also fetches checksums.txt by the name `checksum.name_template` produces, and untars, so `archives.formats` matters too -- rename either and every consumer's job fails at install, with `make check` green and a release already out. The "three things" framing read as exhaustive, so it is now an explicit list with no count. **The warning was only in the file nobody has open when the mistake happens.** .goreleaser.yaml said nothing about the action at all. Dropping Intel macOS (#180) is the cited example of a coupled change and it landed here with no pointer anywhere a maintainer editing `builds.ignore` would see it. Each of the four blocks the action reads -- builds.ignore, archives, checksum, release -- now says so where it is edited. **The tag-glob rationale was left contradicting the new paragraph two lines below it.** CLAUDE.md, release.yml and docs/releasing.md all justified `v*.*.*` as keeping out "the moving major tag #29 needs" -- a tag that will now never exist here, since the action has its own repository. A guard standing on a reason a reader can disprove is a guard the next person relaxes. All three now give the reason that is still true: goreleaser refuses a non-semver tag, and `v1` and `v1.2` are not semver, so a bare `v*` would start a run that could only fail. The old reason is kept as history where it is worth knowing, with "do not relax it" said outright. **The present tense was ahead of reality.** CLAUDE.md said the action "lives in" the new repository while that repository holds only a LICENSE and its first pull request is open. It now says the action is *built* there and has not shipped, and docs/github-actions.md -- the only user-facing mention, which still routed readers to #29 with no hint the repository exists -- says the same thing from the reader's side, and that this page stays the canonical copy of the recipe until the action lands. Also, found while in that file: the workflow example still claimed no release binaries were published and installed `@latest`. v0.1.0 is out, so it pins a tag, and notes that `go install` produces no version stamp.
willkg
force-pushed
the
action-moved
branch
from
September 22, 2026 11:12
c537fde to
d2fded7
Compare
willkg
force-pushed
the
action-moved
branch
from
September 22, 2026 12:02
d2fded7 to
5c3c204
Compare
markfluence-action reached v1.0.0 and mozilla/markfluence-demo publishes through it, so markfluence stops documenting how to hand-roll a CI workflow and points at the thing that does it. **docs/github-actions.md is deleted.** It predated the action: it taught the hand-rolled recipe and accumulated the reasoning for why a CI publish is shaped the way it is. Keeping it would mean maintaining a parallel implementation of what the action does. That copy had already rotted, which is the argument rather than an aside. It carried three bugs the action had fixed and it had not: a "publish everything" fallback that diffed against the first commit and therefore omitted any file added in that commit; a plain `docs/**/*.md` pathspec that silently misses top-level files; and a newline-delimited list through bare xargs, which splits `docs/release notes.md` into two arguments and aborts outright on an apostrophe. Anyone who pasted that recipe got all three. Everything it covered that a *consumer* needs now lives in the action's README (mozilla/markfluence-action#8): the service-account recommendation and why a personal token is the wrong one, whether the repository is even the right source of truth and the explicit do-not-run when it is not, the note-on-the- page convention, what --force actually overrides and why the second check makes it non-optional, the two republishing costs beyond watcher mail, exit codes and the skipped-not-failed contract, and the page_id prerequisite. **The hand-rolled recipe is not carried anywhere, deliberately.** The action's README is user documentation for people using the action, and a recipe for not using it does not belong there. It loses nothing: three of its four gotchas -- deletions, the empty-list guard, and -z/xargs -0 -- are the action's own internals that a user never touches, and the fourth, the `:(glob)` pathspec prefix, is user-facing and documented under "How `files` works". All four remain in publish/publish.sh's comments, which is where reasoning about the implementation belongs. The README gains a "Publishing from CI" section under Usage -- a working step and a pointer -- since that is where someone looking for CI will look. The feature bullet links the action too. CLAUDE.md records that there is deliberately no CI document here and why, so the next person does not helpfully recreate one. It also no longer says the action has not shipped, and _plans/047 no longer reads as pending. .goreleaser.yaml and release.yml called it "#29's action"; naming the repository is clearer now that it exists, and the tag-glob rationale in both says the moving major tag lives in markfluence-action and never here. _plans/ still references the deleted file by name in three places. Left alone: those are the record of what was true when each plan was written. Refs #29.
willkg
force-pushed
the
action-moved
branch
from
September 22, 2026 12:20
5c3c204 to
b368c88
Compare
47 files and 15k lines sitting beside docs/ invite two wrong conclusions: that they are current, and that they are safe to delete. This answers both. The first is the one that actually misleads. A plan describes what was intended when it was written and is not revised to match what shipped, so a reader who takes one as documentation gets the state of the world at some past commit. The file says that outright, and names the order of precedence: --help, docs/, CLAUDE.md, and the code wins over all three. The second came up while considering moving them to a personal vault, which is why the reasons are counted rather than asserted: 12 Go files cite a plan by number, docs/guarantees.md 14 times, docs/root-model.md 10, and 22 commit messages -- and that last set can never be fixed. Those citations sit exactly where code looks arbitrary and the reasoning is too long to inline, so a pointer into a notebook nobody else can open is a dead end at the moment it is needed. They are also versioned with the code they describe, which a notebook cannot be. Also documents the workflow they come out of -- issue, plan committed on its own, branch, then docs -- and what the recurring sections mean, since the section names were chosen by habit rather than by design and "Not in scope" is the most re-read of them: it is the answer to "why doesn't it just...". One note in it earns its place beyond orientation: a Confluence finding that lives only in a plan should be promoted to docs/confluence/, which is the canonical home. Plans are where those get measured, not where they belong. Two claims in the first draft were wrong and are corrected: 12 Go files rather than 15 (15 is the number of citation *lines*), and plans do not consistently say "Closes #NNN" -- 039 says "Implements #139".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
markfluence-action shipped as v1.0.0, and mozilla/markfluence-demo publishes through it. So markfluence stops documenting how to hand-roll a CI workflow and points at the thing that does it.
mozilla/markfluence-action#8 landed first and moved this page's unique content into the action's README, so there is no window where neither repository documents it.
docs/github-actions.mdis deletedIt predated the action — it taught the hand-rolled recipe and accumulated the reasoning for why a CI publish is shaped the way it is. Keeping it now means maintaining a parallel implementation of what the action does.
That copy had already rotted, which is the argument rather than an aside. It carried three bugs the action had fixed and it had not:
docs/**/*.mdpathspec, which as a git pathspec silently misses top-level filesxargs, which splitsdocs/release notes.mdinto two arguments and aborts outright on an apostropheAnyone who pasted that recipe got all three. I fixed them in the action months of work ago and never here, which is precisely the failure mode a second copy has.
Where its content went
Everything a consumer needs is in the action's README as of that PR: the service-account recommendation and why a personal token is the wrong one; whether the repository is even the right source of truth, and the explicit do not run this when it is not; the note-on-the-page convention; what
--forceoverrides and why the second check makes it non-optional; the two republishing costs beyond watcher mail; exit codes and the skipped-not-failed contract; and thepage_idprerequisite.The hand-rolled recipe is not carried anywhere, deliberately. The action's README is user documentation for people using the action, and a recipe for not using it does not belong there.
That loses nothing. Three of its four gotchas — deletions, the empty-list guard,
-z/xargs -0— are the action's own internals a user never touches. The fourth, the:(glob)pathspec prefix, is user-facing and is documented under Howfilesworks. All four remain inpublish/publish.sh's comments, which is where reasoning about the implementation belongs.What markfluence keeps
A "Publishing from CI" section under Usage — a working step and a pointer — because that is where someone looking for CI will look, and a bare link from a docs table is not enough. The
pages:block that makes it take no per-file inputs stays documented here, since that is markfluence's own feature.CLAUDE.mdrecords that there is deliberately no CI document here, and why, so the next person does not helpfully recreate one.Reference cleanup, also in this PR
CLAUDE.mdno longer says the action has not shipped;_plans/047no longer reads as pending..goreleaser.yamlandrelease.ymlcalled it "Ship markfluence as a reusable GitHub Action #29's action" — naming the repository is clearer now that it exists, and the tag-glob rationale in both now says the moving major tag lives in markfluence-action and never here.make checkcannot verify — is unchanged, and still the point of that CLAUDE.md paragraph._plans/still references the deleted file by name in three places. Left alone: those are the record of what was true when each plan was written.After this
#29 can close with a pointer, and
markfluence-demo's# FIXMEcan go from@mainto@v1.