Record 0.1.0's registry digest, and document the module that shipped hidden - #4
Merged
Conversation
The digest is read from the Hex API, not from the publishing terminal:
$ curl -s https://hex.pm/api/packages/beam_mcp/releases/0.1.0
checksum b8c351933260d90844eae1614ae4759cf979d4a524ee139fbbef1c2dfaab5e7f
inserted_at 2026-09-06T20:57:51.749883Z
has_docs true
A checksum printed by the machine that built the tarball attests to that
machine. The registry's value is what a consumer actually fetches, so that is
the one recorded.
The tag is annotated: git rev-parse v0.1.0 gives 69c8159, the tag object, not
the commit. The commit is 2add129 and equals main. Both are recorded so nobody
compares the wrong pair and thinks the tag is misplaced.
Also recorded: two hexdocs warnings, reproduced with mix docs rather than taken
from the publish output.
warning: documentation references module "BeamMCP.Server" but it is hidden
BeamMCP.Server carries @moduledoc false, inherited verbatim from the tree this
was extracted from, where it was internal and the annotation was true. It is now
the package's principal public module and ToolCatalog's docs link to it, so the
published docs point at a module hexdocs will not render.
The annotation stopped being true the moment the code left the umbrella. Nothing
caught it because a hidden module is not a compile warning and the gate does not
run mix docs -- which is its own gap, and a candidate gate step rather than a
one-off fix.
Signed-off-by: Ayla Croft <aylacroft@proton.me>
warning: documentation references module "BeamMCP.Server" but it is hidden
warning: documentation references module "BeamMCP.Server" but it is hidden
after: 0 warnings
@moduledoc false came across verbatim in the extraction. In the umbrella it was
an internal module and the annotation was true. Here it is the package's
principal public module and BeamMCP.ToolCatalog's docs link to it, so 0.1.0's
published docs point at a module hexdocs will not render.
The moduledoc says what the module is -- one message in, one response out, no
process and no state of its own -- how the two eras are told apart, and what the
host must supply, with the new/1 call written out. It does not restate the
README.
Version 0.1.1. The change is documentation only: no behaviour, no API, no test
touched, and mix test is unchanged at 33.
Worth naming rather than just fixing: nothing caught this. A hidden module is
not a compile warning, and the gate does not run mix docs. The gate has a step
for every claim the package makes except the one about its own documentation.
That is a gate gap, not a one-off, and it is recorded as such.
Signed-off-by: Ayla Croft <aylacroft@proton.me>
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
1 participant
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.
Two commits.
78bca05— record 0.1.0The digest is read from the Hex API, not the publishing terminal:
A checksum printed by the machine that built the tarball attests to that machine. The registry's value is what a consumer actually fetches.
Both tag SHAs are recorded, because
git rev-parse v0.1.0returns69c8159— the annotated tag object, not the commit. The commit is2add129and equalsmain. Recording only one invites someone to compare the wrong pair and conclude the tag is misplaced.1f4109d— documentBeamMCP.Server(0.1.1)@moduledoc falsecame across verbatim in the extraction. In the umbrella it was an internal module and the annotation was true. Here it is the package's principal public module andToolCatalog's docs link to it — so 0.1.0's published docs point at a module hexdocs will not render.Documentation only: no behaviour, no API, no test touched, suite unchanged at 33.
The part worth more than the fix
Nothing caught this. A hidden module is not a compile warning, and the gate does not run
mix docs. The gate has a step for every claim the package makes except the one about its own documentation — so the first person to see the defect was a reader of the published page.That is a gate gap rather than a one-off, and it is recorded as one. Adding
mix docsas a gate step is not in this PR: it wants its own red, and this PR is already two things.