Conversation
Review of the STE100 rewrite found places where it changed or lost something a reader needs, plus errors that predate it: - round trip: restore the missing verb and "content survives" - batch publish: an unchanged page gets no new version, but it is not free of requests - --root: diff redirects .env too, and check honours the per-file root - find: it resolves to folder ids as well as page ids - Homebrew completions: say there is nothing more to do - moving assets: an attachment is named by its base name (_plans/029), so a move keeps it and only a rename orphans the old one; a page referencing two assets with one base name is refused - error codes: add CONFLICT - schema example: add space-info and user-info - create workflow: use one filename throughout
Short sentences, active voice, no gerund headings, no contractions or em dashes. Two lines keep their original shape on purpose: the welcome, which is warm by design, and the reason for recording Confluence findings, which loses its point in STE100.
CONTRIBUTING named vet, fmt-check, test, build, and lint, and left out docs-check, which the Makefile runs between fmt-check and test.
- find: a folder id is also the target of children and export, not only a parent - .env warning: any group or world permission bit fires it, not only read - move an asset: drop the L3 citation, whose one-line statement still says identity follows location - the divergence refusal and the unchanged-body skip both need the action log, which only exists under a markfluence.yaml; say so, and tell one-file-at-a-time users what they give up without one - archive: it also holds completions/ - Location of documentation: include usage, and drop "additional" - rewrap two lines past 80 columns
Prose only: every id, label, status, code identifier, issue and plan reference, measured date, link target, and the WalkDir block are unchanged. The table statements are reworded without changing meaning, and the L5 note's quotation of its own law follows the new wording. Known stale content is carried over as-is and corrected separately.
- L3: the statement said identity follows the asset's location. It follows the file name: convert.AttachmentFilename returns the base name, and planAttachments matches by that name and restamps a moved asset's recorded path. Statement corrected; label and status (Holds) unchanged. The note now cites the code rather than a plan. - Orphaned attachments: identity is the file name, and #99 tracks the prune; the README no longer tells anyone to remove them by hand. - Symlinks: convert.withinRoot no longer exists; images are checked through root.FS, an os.Root. Record the remaining limit: the upload opens an ordinary path, so a directory swapped for a symlink between the check and the upload is a race S2 does not cover.
Prose only: every code block, backtick token, link target, and issue reference is unchanged.
Prose only: every code block, backtick token, link target, and swatch value is unchanged. The long notes for parent, labels, page_width, and page_status move out of the field table into a subsection each, since a table cell cannot hold a 15-sentence paragraph under STE100's limits.
Prose only: every command, code block, link target, and issue reference is unchanged. The workflow's run in step 4 becomes a numbered sequence.
Prose only: every code block, backtick token, link target, and issue, plan, and CVE reference is unchanged, and so are the four headings other documents link to. The pages: heading keeps its em dash, because the anchor #pages--page-metadata-for-a-pristine-file is derived from it.
Checked against schema/json-output/v1.json: - user-find truncated: the rewrite said there are no other matches; it means they cannot be counted - error codes: add CONFLICT - status verbs: add export (wrote, skipped, "" and its attachment verbs), which never emits failed; name children's status field as content status, not a verb - export can report more than one page under --depth and --space - attachment-*: a page lookup failure is a single failure with page_id and no filename - body_changed is also null with no base or a base with no sha - page_status null means different things on update/create and on page-info/read - space-info, user-info and children --space also report failure as a stderr error object - a bad-flag error object can have an empty command
Checked against the code: - space: create refuses a --space that disagrees with frontmatter space (resolveSpace), so flag > frontmatter holds for page_width only - title: update keeps the live title when it is absent; create needs it or --title, and an empty title fails both - page_status is also a single-value field (scalarFields) - create writes title and page_width back, so a later update asserts the width it chose - a .md parent can be a page published earlier, and must be inside the root and not a symlink (parentPublished) - doc links resolve to any .md under the root, not only siblings - <!-- bg:COLOR --> is a second comment directive - restore meanings the rewrite changed: which unresolved links are reported, raw storage passing through unconverted, list tags written like <br>, and storage recording cells as paragraphs
Checked against .goreleaser.yaml, release.yml, buildinfo and the
Makefile:
- verify step: the binary prints the version without the v
(ldflags {{.Version}}); the rewrite turned "not markfluence
--version" into an order the next block broke, and the reason given
was backwards. The Homebrew check now runs the cask binary by its
full path, since a make-install build earlier on PATH would answer
- rehearsal: goreleaser's hooks run go mod tidy and make completions,
so clean completions/ too and check git status
- step 4: make check and the final publish are workflow steps, not
goreleaser
- recovery: no draft exists when the run fails before goreleaser
creates the release; a failed publish step needs only a re-run of gh
release edit; the prose now names the cask branch
- wording the rewrite changed: the release job (not you) pushes the
cask branch, skip_upload stops the cask push, and admins cannot
force a merge
Checked against the code: - the log: the rewrite said nothing depends on it; update's moved-page refusal and unchanged-body skip both do, though no run fails for want of it - --no-persist still appends an action-log line (recordAction checks only dry-run) - a link outside the root is replaced with LINK BROKEN, not left as written, and check (#42) already audits a tree offline - an image resolves relative to its page's directory; the root only bounds it - an attachment's name is its base name, so the root decides its recorded path, not its name; moving an image keeps its attachment - diff also shares its root cache with .env resolution; create, update and attachment-upload are the commands that print the root - preflight converts every file before reserve (#127) - page_status is graded with title, page_width and labels - info is page-info
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.
Part of #165.
Replaces #183, which GitHub closed when its head branch was renamed from
readme-fixto this one.An ASD-STE100 (Simplified Technical English) pass over seven documents, plus the corrections that reviewing them turned up.
README.md
--rootscope (diffredirects.envtoo,checkhonours the per-file root),findreturning folder ids, and the.envwarning firing on any group or world bit.main: moving an asset keeps its attachment (the name is the base name), the error-code list was missingCONFLICT, theschemaexample was missingspace-infoanduser-info, and the create workflow used two different filenames.markfluence.yaml, and tells one-file-at-a-time users what they give up without one.CONTRIBUTING.md
docs-checkamong whatmake checkruns.docs/guarantees.md
withinRootparagraph in Symlinks. It also records the upload race (Attachment upload reads outside the os.Root that checked it #186) as a known limit of S2.docs/json-output.md
CONFLICTadded to the error codes;export's status verbs (it never emitsfailed) and its multi-page results under--depth/--space; whenbody_changedandpage_statusare null;space-info,user-infoandchildren --spacereporting failure on stderr; an emptycommandon a bad-flag error.docs/markdown_file.md
parent,labels,page_widthandpage_statusmove out of the field table into a subsection each.createrefuses a--spacethat disagrees with frontmatter, so flag > frontmatter holds only for width;titleis optional forupdate;page_statusis a single-value field;createwritespage_widthback, so a laterupdateasserts it; a.mdparent can be a page published earlier; doc links resolve to any.mdunder the root;<!-- bg:COLOR -->is a second comment directive.docs/releasing.md
v; the Homebrew check runs the cask binary by full path so amake installbuild onPATHcannot answer; the rehearsal'sgo mod tidyandmake completionshooks;make checkand the final publish are workflow steps, not goreleaser; recovery when no draft exists, or when only the publish step failed.docs/root-model.md
updatedoes depend on the log for its two checks;--no-persiststill writes a log line; a link outside the root isLINK BROKEN, andcheckexists; an image resolves relative to its page; an attachment's name is its base name, so moving an image keeps it;diffalso redirects.envunder--root; preflight converts before reserve;infoispage-info.Each of these four files has two commits: the rewrite, then the fixes from a code review of it.
_plans/048_principles.md(onmain) plans reshapingguarantees.mdinto design principles with no statuses, so these status corrections are the last of that kind.