Refine ENSRainbow Docs #1075
Refine ENSRainbow Docs #1075
Conversation
🦋 Changeset detectedLatest commit: 1abee90 The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
lightwalker-eth
left a comment
lightwalker-eth
left a comment
There was a problem hiding this comment.
@djstrong Here's some quick feedback on enhanced patterns we could use.
docs/ensnode.io/src/content/docs/ensrainbow/concepts/glossary.mdx
Outdated
Show resolved
Hide resolved
docs/ensnode.io/src/content/docs/ensrainbow/concepts/glossary.mdx
Outdated
Show resolved
Hide resolved
docs/ensnode.io/src/content/docs/ensrainbow/concepts/label-sets-and-versioning.mdx
Outdated
Show resolved
Hide resolved
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
This pull request refines ENSRainbow documentation by deduplicating term definitions and replacing inline explanations with centralized glossary links, as part of addressing issue #932.
Key changes include:
- Expanded the glossary from a table format to detailed individual sections for each term
- Replaced verbose inline documentation with links to the centralized glossary throughout the codebase
- Updated documentation to reflect the availability of the
searchlightlabel set (version 0)
Reviewed changes
Copilot reviewed 26 out of 27 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
terraform/variables.tf |
Updated variable descriptions to link to glossary definitions |
pnpm-lock.yaml |
Added bloom-filters package and dependencies |
packages/ensrainbow-sdk/src/client.ts |
Added glossary link for "heal" definition in JSDoc |
packages/ensnode-sdk/src/ensrainbow/types.ts |
Replaced inline label set definition with glossary link |
packages/ensnode-sdk/src/ens/types.ts |
Added glossary reference for labelhash definition |
docs/ensnode.io/src/content/docs/ensrainbow/usage/configuration.mdx |
Replaced verbose descriptions with glossary links |
docs/ensnode.io/src/content/docs/ensrainbow/usage/available-label-sets.mdx |
Added searchlight dataset and updated its availability status |
docs/ensnode.io/src/content/docs/ensrainbow/index.mdx |
Added glossary links for heal terminology |
docs/ensnode.io/src/content/docs/ensrainbow/faq.mdx |
Updated searchlight description and improved code formatting |
docs/ensnode.io/src/content/docs/ensrainbow/contributing/index.mdx |
Simplified environment variable documentation with glossary links |
docs/ensnode.io/src/content/docs/ensrainbow/concepts/typescript-interfaces.mdx |
Added glossary link for label set terminology |
docs/ensnode.io/src/content/docs/ensrainbow/concepts/performance.mdx |
Updated searchlight dataset metrics |
docs/ensnode.io/src/content/docs/ensrainbow/concepts/label-sets-and-versioning.mdx |
Added glossary links to key terms |
docs/ensnode.io/src/content/docs/ensrainbow/concepts/glossary.mdx |
Expanded from table to detailed sections with environment variables |
docs/ensnode.io/src/content/docs/ensrainbow/concepts/data-model.mdx |
Added glossary links and rainbow record documentation |
docs/ensnode.io/src/content/docs/ensrainbow/concepts/creating-files.mdx |
Renamed section and improved formatting |
docs/ensnode.io/src/content/docs/docs/reference/terminology.mdx |
Added glossary cross-reference for labelhash |
apps/ensrainbow/src/utils/rainbow-record.ts |
Added glossary link in interface documentation |
apps/ensrainbow/src/lib/rainbow-record.ts |
Added glossary link in interface documentation |
apps/ensrainbow/src/lib/database.ts |
Added data model documentation reference |
apps/ensrainbow/src/commands/convert-csv-command.test.ts |
Updated comment for accuracy |
apps/ensrainbow/scripts/download-prebuilt-database.sh |
Simplified comments with glossary link |
apps/ensrainbow/scripts/download-ensrainbow-files.sh |
Simplified comments with glossary link |
apps/ensrainbow/package.json |
Added bloom-filters dependency |
apps/ensrainbow/.env.local.example |
Replaced verbose comments with documentation links |
apps/ensindexer/.env.local.example |
Simplified configuration comments with glossary links |
.changeset/fifty-spies-call.md |
Added changeset for patch releases |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| variable "ensindexer_label_set_id" { | ||
| type = string | ||
| description = "The label set ID that ENSIndexer will request from ENSRainbow for deterministic label healing (e.g., 'subgraph', 'ens-test-env')" | ||
| description = "The label set ID that ENSIndexer will request from ENSRainbow for deterministic label healing. See https://ensnode.io/ensrainbow/concepts/glossary/#label_set_id for definition." |
There was a problem hiding this comment.
The anchor in the URL should use hyphens instead of underscores. Markdown heading "Label Set ID" generates the anchor "#label-set-id", not "#label_set_id". The correct URL should be: https://ensnode.io/ensrainbow/concepts/glossary/#label-set-id
| variable "ensindexer_label_set_version" { | ||
| type = string | ||
| description = "The label set version that ENSIndexer will request from ENSRainbow for deterministic label healing (e.g., '0', '1')" | ||
| description = "The label set version that ENSIndexer will request from ENSRainbow for deterministic label healing. See https://ensnode.io/ensrainbow/concepts/glossary/#label_set_version for definition." |
There was a problem hiding this comment.
The anchor in the URL should use hyphens instead of underscores. Markdown heading "Label Set Version" generates the anchor "#label-set-version", not "#label_set_version". The correct URL should be: https://ensnode.io/ensrainbow/concepts/glossary/#label-set-version
| variable "ensrainbow_label_set_id" { | ||
| type = string | ||
| description = "The label set ID that ENSRainbow will offer to its clients (e.g., 'subgraph', 'ens-test-env')" | ||
| description = "The label set ID that ENSRainbow will offer to its clients. See https://ensnode.io/ensrainbow/concepts/glossary/#label_set_id for definition." |
There was a problem hiding this comment.
The anchor in the URL should use hyphens instead of underscores. Markdown heading "Label Set ID" generates the anchor "#label-set-id", not "#label_set_id". The correct URL should be: https://ensnode.io/ensrainbow/concepts/glossary/#label-set-id
| variable "ensrainbow_label_set_version" { | ||
| type = string | ||
| description = "The highest label set version that ENSRainbow will offer to its clients (e.g., '0', '1')" | ||
| description = "The highest label set version that ENSRainbow will offer to its clients. See https://ensnode.io/ensrainbow/concepts/glossary/#label_set_version for definition." |
There was a problem hiding this comment.
The anchor in the URL should use hyphens instead of underscores. Markdown heading "Label Set Version" generates the anchor "#label-set-version", not "#label_set_version". The correct URL should be: https://ensnode.io/ensrainbow/concepts/glossary/#label-set-version
|
|
||
|
|
There was a problem hiding this comment.
There's a malformed markdown code block structure. Line 462 closes a code block with triple backticks, but there's an extra empty line (463) followed by another empty line (464) and then a new bash code block starts on line 465. The structure should be cleaned up - the empty lines 463-464 between the closing backticks and the opening bash block appear to be unintentional formatting errors.
| The `.ensrainbow` file format uses two main message types: | ||
|
|
||
| ```protobuf | ||
| // Protobuf serialization format for [rainbow records](/docs/ensrainbow/concepts/glossary#rainbow-record) |
There was a problem hiding this comment.
Markdown link syntax in a protobuf code block won't render as a clickable link. Inside code blocks, markdown formatting is not processed. Consider moving this comment outside the code block or using plain text within the code block.
| // Protobuf serialization format for [rainbow records](/docs/ensrainbow/concepts/glossary#rainbow-record) | |
| // Protobuf serialization format for rainbow records (see /docs/ensrainbow/concepts/glossary#rainbow-record) |
lightwalker-eth
left a comment
lightwalker-eth
left a comment
There was a problem hiding this comment.
@djstrong Thanks for updates. Shared a few small comments and it looks like there's a few interesting comments added by GitHub's AI.
Please take the lead to merge when ready 👍
docs/ensnode.io/src/content/docs/ensrainbow/concepts/label-sets-and-versioning.mdx
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 26 out of 27 changed files in this pull request and generated 2 comments.
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
apps/ensrainbow/package.json
Outdated
| "@ensnode/ensrainbow-sdk": "workspace:*", | ||
| "@ensnode/ensnode-sdk": "workspace:*", | ||
| "@hono/node-server": "^1.4.1", | ||
| "bloom-filters": "^3.0.4", |
There was a problem hiding this comment.
The bloom-filters package is added as a dependency but is not imported or used anywhere in the codebase. If this is intended for future use, consider adding a comment in the code or documentation explaining its purpose. Otherwise, this dependency should be removed to avoid bloating the package.
| "bloom-filters": "^3.0.4", |
| --- | ||
| title: What is ENSRainbow? | ||
| description: ENSRainbow is an open-source service that heals unknown ENS names by converting encoded labelhashes back to human-readable labels. | ||
| description: ENSRainbow is an open-source service that [heals](/docs/ensrainbow/concepts/glossary#heal) unknown ENS names by converting encoded labelhashes back to human-readable labels. |
There was a problem hiding this comment.
Markdown link syntax in YAML frontmatter description will not be rendered as a link. The description field is typically used for meta tags and OpenGraph tags where markdown is not processed. It will appear as plain text: "heals". Consider using plain text without the link, e.g., "ENSRainbow is an open-source service that heals unknown ENS names by converting encoded labelhashes back to human-readable labels."
| description: ENSRainbow is an open-source service that [heals](/docs/ensrainbow/concepts/glossary#heal) unknown ENS names by converting encoded labelhashes back to human-readable labels. | |
| description: ENSRainbow is an open-source service that heals unknown ENS names by converting encoded labelhashes back to human-readable labels. |
…sed dependencies from package.json
Deduplication of terms as part of issue #932