README review, and split contributor docs into CONTRIBUTING.md - #7
Merged
Conversation
Moves the dead-letter screenshot to just after the opening paragraph. It is the fastest way to show what the package does, and it was buried 440 lines down where only someone already reading the examples would find it. The Example workflows section now points back to it. Four corrections, all found by checking the prose against the code: - "Source → Create" is not an operation. It is "Source → Get or Create"; a plain create was deliberately never exposed, because source names are unique per project and `POST /sources` 409s on the second run. - The development section told you to run `hookdeck listen <source> <connection>`, directly contradicting the section above it explaining that naming a connection is wrong — it attaches the CLI to one connection, leaving test events with no session and no event recorded. - The output sample showed 8 of the 13 fields under `hookdeck`, omitting `verified`, `eventUrl`, `originalIp`, `connectionName` and `destinationName` while presenting itself as the shape of the item. Now complete, and says which fields are optional and why `verified` is a string about the provider's signature, not the trigger's. - "~150 platform types" was stale the moment Hookdeck added one. Dropped the number rather than pinning a second copy of it. Adds the thing a reader is most likely to be stopped by: n8n Cloud installs verified community nodes only, and this package is not on that list yet, so it is self-hosted for now. Also records that the bootstrapping commands need `--otp` under 2FA, and that the deprecation 404s for a few minutes while npm's read path catches up with its write path. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ab8ayFXEtVZQ14PQ9kthSc
The README was 686 lines, and a quarter of it was for people changing the code rather than using the nodes — layout, npm scripts, linking into a local n8n, the release process, SemVer rules, and a bootstrapping procedure that runs once in the package's lifetime. README keeps what a user needs and ends at Compatibility with a pointer. 523 lines, and the last thing before Resources is now about running the nodes rather than publishing them. Four references pointed at "README § Releasing" — two in publish.yml's header comment, two in the release skill. Repointed, along with the cross-file link to How events reach n8n, which was an in-page anchor and would have silently resolved to nothing once it lived in another file. Two additions while the material was in hand, both things that cost time here and are not obvious from the code: the pre-PR command list with why verify-package-load exists at all, and the fact that node descriptions are read once at startup — so a display name, notice or hint change needs n8n restarted, and a rebuild alone leaves the old UI in place. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ab8ayFXEtVZQ14PQ9kthSc
leggetter
changed the title
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.
Screenshot moved up
It now sits just after the opening paragraph instead of 440 lines down, where only someone already reading the Example workflows section would ever see it. The Example workflows section points back to it.
Corrections
Found by checking the prose against the code, not by re-reading it:
Source → CreateSource → Get or Create. A plain create was deliberately never exposed: source names are unique per project, soPOST /sources409s on a re-run.hookdeck listen 5678 <source> <connection>in Developmenthookdeckverified,eventUrl,originalIp,connectionNameanddestinationNamewere missing from something presented as the shape of the item.Added
--otpunder 2FA, and the deprecation 404s for a few minutes while npm's read path catches up with its write path. Both cost time on the real run.Docs only. Scan passes, 106 tests, all links/anchors/images verified to resolve.