refactor(nav): rename group to 'Generated Package References' + add sync-templates.sh#40
Conversation
The SDK API docs group was labeled 'Generated API Reference', which
clashes with the OpenAPI 'API reference' tab and obscured what it
actually contains (per-language SDK package docs, not REST API
reference). Rename to 'Generated Package References' across:
- docs.json (the live nav label)
- scripts/splice-sdk-nav.py (used by manual splice)
- automation/source-repo-templates/api-docs.{python,typescript,dotnet}.yml
Also adds automation/sync-templates.sh: a helper that clones each SDK
source repo, copies the canonical workflow template, and opens a sync
PR when the workflows diverge. This collapses the manual three-PR
template-sync cadence into one command (or `--dry-run` to preview).
Source-repo workflow updates need a follow-up sync PR per repo via
the new script.
github-actions
Bot
added
area:content
📝 WalkthroughWalkthroughThis PR renames the "Generated API Reference" navigation group to "Generated Package References" across docs.json, splice scripts, and three language workflow templates. It introduces automation/sync-templates.sh to distribute canonical per-language workflows to target repositories with dry-run and auto-merge support, and documents the sync process. ChangesSDK Navigation Rename and Distribution
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new synchronization script, automation/sync-templates.sh, to automate the deployment of documentation workflow templates across SDK repositories. It also renames the 'Generated API Reference' navigation group to 'Generated Package References' across configuration files and scripts. Feedback focused on improving the robustness of the sync script, specifically by enhancing error handling during repository cloning, ensuring reliable PR URL capture, and correctly handling scenarios where a pull request already exists.
| pr_url="$(gh pr create \ | ||
| --repo "$target_repo" \ | ||
| --base "$default_branch" \ | ||
| --head "$branch" \ | ||
| --title "ci(api-docs): sync workflow from resq-software/docs" \ | ||
| --body "Sync from canonical template \`automation/source-repo-templates/${template_file}\`. Auto-generated by \`automation/sync-templates.sh\`." \ | ||
| 2>&1 | tail -1)" | ||
| echo "[$lang] $pr_url" | ||
|
|
||
| if [ "$AUTO_MERGE" -eq 1 ]; then | ||
| gh pr merge "$pr_url" --repo "$target_repo" --squash --auto --delete-branch || true | ||
| echo "[$lang] auto-merge enabled" | ||
| fi |
There was a problem hiding this comment.
The current PR creation and merging logic has several issues:
- Brittle URL capture: Using
2>&1 | tail -1is unreliable as it mixes stderr and stdout, potentially capturing error messages as URLs if the command fails. - Existing PR handling:
gh pr createfails if a PR already exists for the branch. The script should handle this by fetching the existing PR's URL to allow the sync to continue (e.g., for auto-merging). - Incorrect return status: The function returns 0 even if PR creation or merging fails because the last command executed is an
echo. This prevents the main loop from correctly reporting failures.
The suggested refactor addresses these by using a safer capture method, adding a fallback for existing PRs, and ensuring non-zero exit codes on failure.
if ! pr_url=$(gh pr create \
--repo "$target_repo" \
--base "$default_branch" \
--head "$branch" \
--title "ci(api-docs): sync workflow from resq-software/docs" \
--body "Sync from canonical template \`automation/source-repo-templates/${template_file}\`. Auto-generated by \`automation/sync-templates.sh\`." 2>/dev/null); then
# Fallback: if PR already exists, fetch its URL
pr_url=$(gh pr view "$branch" --repo "$target_repo" --json url -q .url 2>/dev/null || true)
fi
if [ -z "$pr_url" ]; then
echo "[$lang] failed to create or find PR" >&2
return 1
fi
echo "[$lang] $pr_url"
if [ "$AUTO_MERGE" -eq 1 ]; then
if ! gh pr merge "$pr_url" --repo "$target_repo" --squash --auto --delete-branch; then
echo "[$lang] auto-merge failed" >&2
return 1
fi
echo "[$lang] auto-merge enabled"
fi| --depth=1 --branch="$default_branch" --quiet 2>/dev/null; then | ||
| echo "[$lang] clone failed for $target_repo" >&2 |
There was a problem hiding this comment.
Hiding stderr from gh repo clone using 2>/dev/null makes it difficult to diagnose failures (e.g., authentication issues or repository permission errors). Removing the redirection will provide better visibility when a sync target fails to clone.
| --depth=1 --branch="$default_branch" --quiet 2>/dev/null; then | |
| echo "[$lang] clone failed for $target_repo" >&2 | |
| if ! gh repo clone "$target_repo" "$clone_dir" -- \ | |
| --depth=1 --branch="$default_branch" --quiet; then |
![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
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@automation/sync-templates.sh`:
- Around line 98-129: The script currently always runs gh pr create for the
fixed head branch stored in local branch="sync/api-docs-template", causing
failures if a PR already exists; change the flow in the block that sets pr_url
so it first checks for an existing open PR for that head (use gh pr list or gh
pr view with --head "$branch" and --repo "$target_repo") and if found, capture
and echo that existing PR URL instead of calling gh pr create, otherwise call gh
pr create as before; ensure pr_url is set to the existing PR URL when reusing
and preserve the existing commit/push steps (git checkout -b "$branch", git push
-u origin "$branch" --force-with-lease) so the create-or-reuse logic around gh
pr create sets the same pr_url variable used by the echo.
In `@scripts/splice-sdk-nav.py`:
- Line 165: The generator expression that builds the English language entry uses
an ambiguous variable name `l`; update the expression in the assignment to `en =
next(...)` to use a descriptive identifier (e.g., `lang` or `language_entry`)
instead of `l` so it satisfies Ruff E741 and improves readability—locate the `en
= next(l for l in docs["navigation"]["languages"] if l["language"] == "en")`
line and replace the `l` identifier throughout that generator expression with
the chosen descriptive name.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1ef15c64-8046-4f20-b037-a3491f5ffba8
📒 Files selected for processing (7)
automation/source-repo-templates/README.mdautomation/source-repo-templates/api-docs.dotnet.ymlautomation/source-repo-templates/api-docs.python.ymlautomation/source-repo-templates/api-docs.typescript.ymlautomation/sync-templates.shdocs.jsonscripts/splice-sdk-nav.py
| local branch="sync/api-docs-template" | ||
| local commit_msg | ||
| commit_msg="$(cat <<EOF | ||
| ci(api-docs): sync workflow from resq-software/docs | ||
|
|
||
| Sync .github/workflows/api-docs.yml from the canonical template at | ||
| automation/source-repo-templates/${template_file} in | ||
| resq-software/docs. | ||
|
|
||
| Generated by automation/sync-templates.sh. | ||
| EOF | ||
| )" | ||
|
|
||
| ( | ||
| cd "$clone_dir" | ||
| git checkout -b "$branch" | ||
| git add .github/workflows/api-docs.yml | ||
| git -c user.email=engineer@resq.software \ | ||
| -c user.name="resq-sw" \ | ||
| commit -m "$commit_msg" | ||
| git push -u origin "$branch" --force-with-lease | ||
| ) | ||
|
|
||
| local pr_url | ||
| pr_url="$(gh pr create \ | ||
| --repo "$target_repo" \ | ||
| --base "$default_branch" \ | ||
| --head "$branch" \ | ||
| --title "ci(api-docs): sync workflow from resq-software/docs" \ | ||
| --body "Sync from canonical template \`automation/source-repo-templates/${template_file}\`. Auto-generated by \`automation/sync-templates.sh\`." \ | ||
| 2>&1 | tail -1)" | ||
| echo "[$lang] $pr_url" |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
for repo in resq-software/npm resq-software/pypi resq-software/dotnet-sdk; do
echo "==> $repo"
gh pr list \
--repo "$repo" \
--state open \
--head sync/api-docs-template \
--json number,url,headRefName,baseRefName \
--jq '.[] | "\(.number) \(.url) [\(.headRefName)->\(.baseRefName)]"'
doneRepository: resq-software/docs
Length of output: 136
🌐 Web query:
gh pr create behavior when PR already exists same head base
💡 Result:
When using GitHub CLI (gh) to create a PR, if the head branch and base branch resolve to the exact same ref within the same repository, gh pr create does NOT proceed; it errors out early. Specifically, gh/cli added an isSameRef check that returns true when head and base point to the same ref in the same repo, and createRun then returns: head branch "<head>" is the same as base branch "<base>", cannot create a pull request [1]. Important nuance: the same branch name across different repositories (e.g., fork vs upstream) is not treated as “same ref”; the code avoids the error for cross-repository PRs even if the branch names match [1]. Separately (different scenario), if you try to create a PR when an open PR for the same head branch already exists, gh pr create reports that the PR already exists and aborts (rather than creating/overwriting another PR) [2][3].
Citations:
- 1: fix: error when head and base refs are identical in pr create cli/cli#12376
- 2: gh pr create should detect and update already existing pull requests cli/cli#5792
- 3:
pr createshoud fail faster if a PR already exists cli/cli#649
🏁 Script executed:
# Verify the gh pr list syntax and jq filter from the suggested fix
# Also check if gh pr create indeed fails on duplicate head/base
# Test: Simulate the suggested check command to verify syntax
gh pr list \
--repo "resq-software/npm" \
--state open \
--head "sync/api-docs-template" \
--base "main" \
--json url \
--jq '.[0].url' 2>&1 | head -20Repository: resq-software/docs
Length of output: 63
Make PR creation idempotent when sync/api-docs-template already has an open PR.
This always calls gh pr create on a fixed head branch. If an open PR already exists, reruns fail and block the workflow. The GitHub CLI aborts with "PR already exists" rather than reusing the existing PR URL.
🛠️ Suggested diff
- local pr_url
- pr_url="$(gh pr create \
- --repo "$target_repo" \
- --base "$default_branch" \
- --head "$branch" \
- --title "ci(api-docs): sync workflow from resq-software/docs" \
- --body "Sync from canonical template \`automation/source-repo-templates/${template_file}\`. Auto-generated by \`automation/sync-templates.sh\`." \
- 2>&1 | tail -1)"
+ local pr_url
+ pr_url="$(gh pr list \
+ --repo "$target_repo" \
+ --state open \
+ --head "$branch" \
+ --base "$default_branch" \
+ --json url \
+ --jq '.[0].url')"
+ if [ -z "$pr_url" ]; then
+ pr_url="$(gh pr create \
+ --repo "$target_repo" \
+ --base "$default_branch" \
+ --head "$branch" \
+ --title "ci(api-docs): sync workflow from resq-software/docs" \
+ --body "Sync from canonical template \`automation/source-repo-templates/${template_file}\`. Auto-generated by \`automation/sync-templates.sh\`." )"
+ fi
echo "[$lang] $pr_url"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@automation/sync-templates.sh` around lines 98 - 129, The script currently
always runs gh pr create for the fixed head branch stored in local
branch="sync/api-docs-template", causing failures if a PR already exists; change
the flow in the block that sets pr_url so it first checks for an existing open
PR for that head (use gh pr list or gh pr view with --head "$branch" and --repo
"$target_repo") and if found, capture and echo that existing PR URL instead of
calling gh pr create, otherwise call gh pr create as before; ensure pr_url is
set to the existing PR URL when reusing and preserve the existing commit/push
steps (git checkout -b "$branch", git push -u origin "$branch"
--force-with-lease) so the create-or-reuse logic around gh pr create sets the
same pr_url variable used by the echo.
|
|
||
| # Find Generated API Reference under en > SDKs > groups | ||
| # Find Generated Package References under en > SDKs > groups | ||
| en = next(l for l in docs["navigation"]["languages"] if l["language"] == "en") |
There was a problem hiding this comment.
Rename the ambiguous generator variable to satisfy Ruff E741.
next(l for l in ...) is flagged as ambiguous and hurts readability. Rename l to a descriptive identifier.
🧩 Suggested diff
- en = next(l for l in docs["navigation"]["languages"] if l["language"] == "en")
+ en = next(lang_entry for lang_entry in docs["navigation"]["languages"] if lang_entry["language"] == "en")📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| en = next(l for l in docs["navigation"]["languages"] if l["language"] == "en") | |
| en = next(lang_entry for lang_entry in docs["navigation"]["languages"] if lang_entry["language"] == "en") |
🧰 Tools
🪛 Ruff (0.15.12)
[error] 165-165: Ambiguous variable name: l
(E741)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/splice-sdk-nav.py` at line 165, The generator expression that builds
the English language entry uses an ambiguous variable name `l`; update the
expression in the assignment to `en = next(...)` to use a descriptive identifier
(e.g., `lang` or `language_entry`) instead of `l` so it satisfies Ruff E741 and
improves readability—locate the `en = next(l for l in
docs["navigation"]["languages"] if l["language"] == "en")` line and replace the
`l` identifier throughout that generator expression with the chosen descriptive
name.
2 participants
Summary
Rename nav group from "Generated API Reference" → "Generated Package References" in `docs.json`, the splice script, and all three SDK source-repo templates. The old name clashed with the OpenAPI "API reference" tab and obscured what the group actually contains (per-language SDK package docs, not REST endpoints).
Add `automation/sync-templates.sh` that clones each SDK source repo (`npm`, `pypi`, `dotnet-sdk`), copies the matching canonical `api-docs..yml`, and opens a sync PR per repo on `sync/api-docs-template`. Replaces the manual three-PR cadence with one command. Supports `--dry-run` and per-language selection.
Test plan
Summary by CodeRabbit
Documentation
Chores