Skip to content

Guide fixes from Guy's onboarding run - #12

Merged
haimbj1 merged 3 commits into
mainfrom
docs/guy-review
Sep 23, 2026
Merged

haimbj1 merged 3 commits into
mainfrom
docs/guy-review

Conversation

@haimbj1

@haimbj1 haimbj1 commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

From Guy's onboarding of fhenix-mainnet-key-share, our own mainnet partner project. He
followed v1.0.1 end to end and said the guide was clear, with three notes. This is
those 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:

curl -sL .../archive/refs/tags/<tag>.tar.gz | shasum -a 256

GitHub answers 404, curl -sL prints the error page, and shasum hashes it:

d5558cd419c8d46bdc958064cb97f963d1ea793866414c025906ec15033512ed

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 -f is not enough: curl then errors but the pipe still hashes empty input and
gives e3b0c442..., another plausible mismatch.

Now:

curl -fsSL "https://github.com/FhenixProtocol/key-share-holders/archive/refs/tags/$TAG.tar.gz" \
  -o /tmp/src.tar.gz && shasum -a 256 /tmp/src.tar.gz

Verified both ways: the right hash with TAG set, and no hash at all when it is not,
because && stops shasum. 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, and
Guy proved one of them bites.

Step 1 now starts with:

export PROJECT=<your GCP project id>
export TAG=<the tag we sent you>        # for example v1.0.1

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, so
git checkout $TAG would silently re-apply the old release. Apply a later release now
re-sets both variables and checks with git describe that 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_access and every verify/ run prints write_access_granted.

Now one word per direction, matching the tooling:

  • Step 8: Grant write access
  • Step 11: Revoke write access

Not included

Finding 27 in the local notes: verify/ reads provider CELs and secret-level IAM, so a
project-level roles/owner can read every share while verify/ reports SUCCESS. On
fhenix-mainnet-key-share that is accepted, because it is ours. For external partners it
would need a new check, which is a code change rather than a doc one.

@haimbj1
haimbj1 requested a review from guya-fhenix September 23, 2026 12:09
Comment thread PARTNER_GUIDE.md Outdated
@haimbj1
haimbj1 requested a review from guya-fhenix September 23, 2026 12:27
@haimbj1
haimbj1 merged commit 29ce725 into main Sep 23, 2026
2 checks passed
@haimbj1
haimbj1 deleted the docs/guy-review branch September 23, 2026 12:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants