Guide fixes from Guy's onboarding run - #12
Merged
Merged
Conversation
guya-fhenix
reviewed
Sep 23, 2026
guya-fhenix
approved these changes
Sep 23, 2026
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.
From Guy's onboarding of
fhenix-mainnet-key-share, our own mainnet partner project. Hefollowed
v1.0.1end to end and said the guide was clear, with three notes. This isthose three, plus one idea from Haim that turned out to fix the first of them properly.
1. The tarball check produced a convincing wrong hash
Guy ran this without substituting the tag:
GitHub answers 404,
curl -sLprints the error page, andshasumhashes it:A normal-looking hash that does not match the release notes. The guide frames that
command as checking what we published, so the mismatch reads as tampering by us, on a
release that is fine. That is the worst failure mode in the document.
Adding
-fis not enough: curl then errors but the pipe still hashes empty input andgives
e3b0c442..., another plausible mismatch.Now:
Verified both ways: the right hash with
TAGset, and no hash at all when it is not,because
&&stopsshasum. The computed value matches the v1.0.1 release notes,3de48fa9....2. Two shell variables
<your-project>appeared 27 times,<tag>three more. Thirty chances to mistype, andGuy proved one of them bites.
Step 1 now starts with:
Nothing else is substituted by hand.
This introduced a trap of its own, which the diff also fixes. Months later, a fresh
shell has no
$TAG, and an old shell may still hold the previous one, sogit checkout $TAGwould silently re-apply the old release. Apply a later release nowre-sets both variables and checks with
git describethat the new tag is what landed.3. "See X under Reference" with no way to get there
Fourteen cross-references named a section and expected scrolling. Now 13 anchor links,
each verified to resolve against a real heading.
Worth noting: two bugs fixed earlier today came from cross-references that were written
and never followed. A link is at least checkable.
4. "Open the write window"
In a document full of terminal commands, "window" reads as a GUI window. The guide also
used three words for one thing: write window, freeze, frozen, while every command
says
grant_write_accessand everyverify/run printswrite_access_granted.Now one word per direction, matching the tooling:
Not included
Finding 27 in the local notes:
verify/reads provider CELs and secret-level IAM, so aproject-level
roles/ownercan read every share whileverify/reports SUCCESS. Onfhenix-mainnet-key-sharethat is accepted, because it is ours. For external partners itwould need a new check, which is a code change rather than a doc one.