feat: Enhanced documentation sync workflow with config management and regex filtering #251
Conversation
|
Caution Review failedThe pull request is closed. WalkthroughThe updates introduce regex-based filtering for API documentation file syncing, add a sanitized config file synchronization step, and enhance workflow customization in the GitHub Actions documentation and workflow. Supporting scripts and configuration files are added or updated to automate config block updates in documentation and reflect new workflow behaviors. Changes
Sequence Diagram(s)sequenceDiagram
participant Workflow as GitHub Actions Workflow
participant SourceRepo as genlayer-node repo
participant DocsRepo as docs repo
participant Script as update-config-in-setup-guide.js
SourceRepo->>Workflow: Trigger workflow (with paths, regex filters, tag)
Workflow->>SourceRepo: Clone repo, fetch API files and config.yaml.example
Workflow->>Workflow: Sanitize config.yaml (remove sections, replace URLs)
Workflow->>DocsRepo: Sync sanitized config.yaml to content/validators/
Workflow->>Workflow: Filter API files using regex
Workflow->>DocsRepo: Sync filtered API files to docs/api/rpc/gen|debug
Workflow->>Script: Run update-config-in-setup-guide.js
Script->>DocsRepo: Update YAML block in setup guide
Workflow->>DocsRepo: Commit and create PR with summary of changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Suggested reviewers
Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (6)
✨ Finishing Touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for genlayer-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
scripts/update-config-in-setup-guide.js (2)
31-31: Consider making regex patterns more robust.The current regex patterns work but could be improved for maintainability:
Consider these enhancements for better reliability:
// Make the primary pattern more flexible with whitespace - const configPattern = /(You can use the following example configuration[^`]*```yaml\n)([\s\S]*?)(\n```)/; + const configPattern = /(You can use the following example configuration[^`]*```yaml\r?\n)([\s\S]*?)(\r?\n```)/; // Make fallback pattern more specific to avoid false matches - const fallbackPattern = /(```yaml\n)([\s\S]*?)(\n```)/; + const fallbackPattern = /(```yaml\r?\n)([\s\S]*?)(\r?\n```)/g;This handles different line ending formats and makes the fallback pattern more explicit.
Also applies to: 47-47
52-52: Enhance validation logic for better accuracy.The current validation checks are good but could be more comprehensive:
- if (matches[2].includes('contractmanageraddress') || matches[2].includes('consensus:')) { + if (matches[2].includes('contractmanageraddress') || + matches[2].includes('consensus:') || + matches[2].includes('rollup:') || + (matches[2].includes('zksyncurl') && matches[2].includes('node:'))) {This provides better detection of the validator config block by checking for multiple distinctive fields.
.github/workflows/sync-docs-from-node.yml (3)
620-624: Update PR body – missing the newly-introduced script
The autogenerated PR body omitsnpm run node-update-config, yet the workflow runs it.
Add it to keep the PR description accurate.- - `npm run node-generate-api-docs` + - `npm run node-update-config` + - `npm run node-generate-api-docs`
445-463: Deletion loop can silently skip unmatched files whenDELETEDis undefined
You guard withDELETED=${DELETED:-0}, butset -euo pipefailturns unset variables into errors (-u).
Because the parameter expansion occurs before this assignment, the script is still safe, but
readability suffers. Consider initialisingDELETED=0next toADDED/UPDATEDfor symmetry.
196-206: Trailing whitespace harms YAML linting
yamllintflags several trailing-space lines, e.g. 196, 199, 202…
These won’t break the workflow, but fixing them silences CI noise.Also applies to: 246-246, 285-285, 340-340, 402-402, 457-457
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
.github/workflows/README.md(4 hunks).github/workflows/example-trigger-from-node.yml.example(1 hunks).github/workflows/sync-docs-from-node.yml(12 hunks)content/validators/config.yaml(1 hunks)package.json(1 hunks)scripts/update-config-in-setup-guide.js(1 hunks)
🧰 Additional context used
🧠 Learnings (6)
📓 Common learnings
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, enhance command documentation in pages/validators/setup-guide.mdx when new features are added to existing commands
content/validators/config.yaml (7)
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update genesis block configuration in the consensus section of pages/validators/setup-guide.mdx when network upgrades occur
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update configuration examples with new contract addresses in pages/validators/setup-guide.mdx when applicable
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/changelog.mdx : When updating validator documentation for new releases, add new version entries at the top of pages/validators/changelog.mdx in reverse chronological order and use consistent format: # v0.x.x, ## New features, ## Bug fixes, ## Misc
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, enhance command documentation in pages/validators/setup-guide.mdx when new features are added to existing commands
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : Consensus contract addresses change with network upgrades and must be updated in relevant configuration examples
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : Genesis block numbers are specified for faster node startup and should be updated in configuration examples when necessary
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update version references in download examples and version lists in pages/validators/setup-guide.mdx
package.json (4)
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to scripts/**/*.{js,ts} : Build-time generation scripts are located in the scripts directory
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to scripts/generate-full-docs.js : Full documentation concatenation is performed by scripts/generate-full-docs.js
Learnt from: epsjunior
PR: #244
File: next-env.d.ts:3-6
Timestamp: 2025-07-09T18:27:44.033Z
Learning: Next.js automatically updates next-env.d.ts file during dependency updates, including adding new type references like "next/navigation-types/compat/navigation" when upgrading versions. These changes are not manual edits and should not be flagged as problematic.
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, enhance command documentation in pages/validators/setup-guide.mdx when new features are added to existing commands
scripts/update-config-in-setup-guide.js (9)
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update configuration examples with new contract addresses in pages/validators/setup-guide.mdx when applicable
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update genesis block configuration in the consensus section of pages/validators/setup-guide.mdx when network upgrades occur
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, enhance command documentation in pages/validators/setup-guide.mdx when new features are added to existing commands
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update version references in download examples and version lists in pages/validators/setup-guide.mdx
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : Consensus contract addresses change with network upgrades and must be updated in relevant configuration examples
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : Genesis block numbers are specified for faster node startup and should be updated in configuration examples when necessary
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/changelog.mdx : When updating validator documentation for new releases, add new version entries at the top of pages/validators/changelog.mdx in reverse chronological order and use consistent format: # v0.x.x, ## New features, ## Bug fixes, ## Misc
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : GenVM diagnostics integration affects the doctor command behavior and should be documented in the setup-guide.mdx file
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to scripts/generate-full-docs.js : Full documentation concatenation is performed by scripts/generate-full-docs.js
.github/workflows/README.md (6)
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, enhance command documentation in pages/validators/setup-guide.mdx when new features are added to existing commands
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update genesis block configuration in the consensus section of pages/validators/setup-guide.mdx when network upgrades occur
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update configuration examples with new contract addresses in pages/validators/setup-guide.mdx when applicable
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to scripts/generate-full-docs.js : Full documentation concatenation is performed by scripts/generate-full-docs.js
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/changelog.mdx : When updating validator documentation for new releases, add new version entries at the top of pages/validators/changelog.mdx in reverse chronological order and use consistent format: # v0.x.x, ## New features, ## Bug fixes, ## Misc
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, update version references in download examples and version lists in pages/validators/setup-guide.mdx
.github/workflows/sync-docs-from-node.yml (2)
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to scripts/generate-full-docs.js : Full documentation concatenation is performed by scripts/generate-full-docs.js
Learnt from: CR
PR: genlayerlabs/genlayer-docs#0
File: CLAUDE.md:0-0
Timestamp: 2025-06-30T14:01:39.620Z
Learning: Applies to pages/validators/setup-guide.mdx : When updating validator documentation for new releases, enhance command documentation in pages/validators/setup-guide.mdx when new features are added to existing commands
🪛 YAMLlint (1.37.1)
content/validators/config.yaml
[error] 64-64: no new line character at the end of file
(new-line-at-end-of-file)
.github/workflows/sync-docs-from-node.yml
[error] 196-196: trailing spaces
(trailing-spaces)
[error] 199-199: trailing spaces
(trailing-spaces)
[error] 202-202: trailing spaces
(trailing-spaces)
[error] 206-206: trailing spaces
(trailing-spaces)
[error] 210-210: syntax error: could not find expected ':'
(syntax)
[error] 246-246: trailing spaces
(trailing-spaces)
[error] 285-285: trailing spaces
(trailing-spaces)
[error] 340-340: trailing spaces
(trailing-spaces)
[error] 402-402: trailing spaces
(trailing-spaces)
[error] 457-457: trailing spaces
(trailing-spaces)
🪛 actionlint (1.7.7)
.github/workflows/sync-docs-from-node.yml
209-209: could not parse as YAML: yaml: line 209: could not find expected ':'
(syntax-check)
🔇 Additional comments (10)
content/validators/config.yaml (1)
1-64: LGTM! Comprehensive validator configuration with appropriate placeholders.The configuration file provides a well-structured template for validator nodes with proper sections for rollup, consensus, logging, node operations, and advanced settings. The placeholder URLs and example contract addresses are appropriate for a template that will be sanitized during sync.
.github/workflows/example-trigger-from-node.yml.example (1)
49-52: LGTM! Updated paths and regex filters align with enhanced workflow capabilities.The changes correctly reflect:
- Updated API documentation paths to the new
/rpc/structure- Added regex filters for selective file syncing:
gen_(?!dbg_).*matches general API files excluding debug variantsgen_dbg_.*matches only debug API filesThis enables fine-grained control over which API documentation files are synchronized.
package.json (1)
6-7: LGTM! Proper integration of config update script into build pipeline.The new
node-update-configscript is correctly integrated into bothdevandbuildworkflows with logical sequencing:
- Generate changelog
- Update setup guide versions
- Update config in setup guide ← New step
- Generate API docs
- Generate full docs
This ensures the setup guide's configuration example stays synchronized with the source config file.
Also applies to: 13-13
scripts/update-config-in-setup-guide.js (1)
1-73: LGTM! Well-structured script with good error handling and fallback logic.The script effectively automates updating the config block in the setup guide with these strengths:
- Proper file existence validation
- Primary pattern matching with contextual anchoring
- Fallback pattern with content verification
- Standalone execution and module export capabilities
- Informative logging with timestamps
.github/workflows/README.md (4)
18-30: LGTM! Comprehensive documentation of new config sync and script integration.The documentation accurately describes:
- Config file sanitization process (ZKSync URL replacement, section removal)
- Integration of the new
update-config-in-setup-guide.jsscript- Regex filtering capabilities for selective API file syncing
This aligns perfectly with the implementation changes in the other files.
48-52: LGTM! Updated example payload reflects new workflow capabilities.The example correctly shows:
- New API documentation paths (
docs/api/rpc/gen,docs/api/rpc/debug)- Regex filter parameters with appropriate default patterns
- Proper JSON structure for the repository dispatch payload
81-87: LGTM! Enhanced manual trigger documentation provides clear guidance.The updated instructions properly document:
- Required tag parameter for branch naming
- Optional parameters with sensible defaults
- Clear parameter descriptions for API paths and regex filters
121-126: LGTM! Clear explanation of regex filtering logic.The documentation effectively explains:
- How regex patterns are applied (filename without extension)
- Default pattern behavior and exclusion logic
- Distinction between general and debug API files
This will help users understand and customize the filtering behavior.
.github/workflows/sync-docs-from-node.yml (2)
65-81: GitHub-expression fallbacks in a bashrun:block are brittle
Inside therun:script the${{ … }}expressions are rendered before bash executes, so
|| 'default'is evaluated by the GitHub expression engine, not by bash.
That works only when the left operand exists; if the property itself is missing the workflow
fails before reaching therun:step.Safer pattern:
echo "source_branch=${{ github.event.client_payload.source_branch || 'main' }}" >> $GITHUB_OUTPUT→ OK
echo "api_gen_path=${{ github.event.client_payload.api_gen_path || 'docs/api/rpc/gen' }}" >> $GITHUB_OUTPUTFor inputs that may truly be
null, wrap withgithub.event.client_payload.api_gen_path != ''
or move the defaulting logic into bash.
502-504: Make sure the newnode-update-confignpm script exists
The workflow callsnpm run node-update-config, but the summary section (lines 620-624) and
package.jsonsnippet in the PR description still list only three node-* scripts.
Double-check that:
package.jsonactually contains
"node-update-config": "node scripts/update-config-in-setup-guide.js"- The summary (
cat > PR_BODY_FILE) includes this script to avoid confusing reviewers.Failing to add the script to
package.jsonwill exit withnpm ERR! missing script.
Implement regex pattern filtering for API gen and debug file synchronization. This allows selective syncing of files based on configurable patterns - gen files use `gen_(?!dbg_).*` to exclude debug files, while debug files use `gen_dbg_.*` pattern. The filtering ensures only relevant files are synced to their respective destinations and properly handles deletions of files that no longer match the patterns.
Add workflow_dispatch inputs for api_gen_path and api_debug_path to allow users to specify custom source paths when manually triggering the sync workflow. This provides flexibility to sync from different directory structures in the source repository. Updated documentation to reflect all available manual trigger parameters.
- Add config.yaml sync step to workflow from config.yaml.example - Replace ZKSync URLs with TODO placeholders during sync - Remove node.dev and node.admin sections using Python YAML parser - Create update-config-in-setup-guide.js script for automatic updates - Add node-update-config to package.json build process - Update workflow documentation to explain config sanitization
dohernandez
force-pushed
the
chore/nod-189-ci-automate-changelog
branch
from
e383560 to
9c2633d
Compare
Description
This PR enhances the documentation sync workflow to provide more flexible and robust synchronization between the genlayer-node and documentation repositories. The changes introduce regex pattern filtering for API documentation files, customizable source paths for manual workflow runs, and automatic config.yaml synchronization with sanitization for security.
Motivation and Context
The previous sync workflow had limitations in file filtering and lacked the ability to sync configuration files. This enhancement addresses several needs:
Summary of Changes
Workflow Enhancements
gen_(?!dbg_).*andgen_dbg_.*)node.devandnode.adminsections using Python YAML parserNew Scripts
scripts/update-config-in-setup-guide.jsto automatically update config content in the validator setup guideDocumentation Updates
Types of Changes
Testing
The changes have been tested locally by:
Checklist:
Additional Notes
The Python-based YAML parsing approach was chosen over AWK for reliability across different YAML indentation styles, ensuring robust config sanitization regardless of formatting variations.
Summary by CodeRabbit
Summary by CodeRabbit
New Features
Documentation
Chores