Skip to content

chore(playbook): update docs content source URL from 'documentation' to 'docs'#615

Open
Feediver1 wants to merge 2 commits into
mainfrom
fix-stale-docs-repo-url
Open

chore(playbook): update docs content source URL from 'documentation' to 'docs'#615
Feediver1 wants to merge 2 commits into
mainfrom
fix-stale-docs-repo-url

Conversation

@Feediver1

Copy link
Copy Markdown
Contributor

Summary

Updates the docs content source URL in local-antora-playbook.yml from the old redpanda-data/documentation to the current redpanda-data/docs.

Why

The repo was renamed from redpanda-data/documentation to redpanda-data/docs previously. GitHub serves an HTTP 301 redirect from the old URL, so Antora's clone still resolves; but the URL string in the playbook becomes the cache key. That means the old URL can persist as a separate cache entry in Netlify build caches, contributing to the multi-axis cache staleness we've been chasing (broken xref attributions pointing at redpanda-data/documentation (branch: main) in build logs).

Using the current canonical name:

  1. Makes the playbook self-documenting and accurate.
  2. Invalidates any stale cache entry keyed on the old name on the next preview build.

Verified during diagnosis of redpanda-data/docs#1734 / #1741

Build logs for those PRs surfaced errors attributed to https://github.com/redpanda-data/documentation (branch: main) even though the docs repo's own playbook had already been updated to use redpanda-data/docs. The remaining old-URL reference is right here — this PR fixes it.

Diff

One line.

- - url: https://github.com/redpanda-data/documentation
+ - url: https://github.com/redpanda-data/docs

No behavioral change to what's fetched (same repo via redirect either way), just the URL string in the cache key.

Companion PR

A matching one-line fix to rp-connect-docs/local-antora-playbook.yml will be opened separately.

🤖 Generated with Claude Code

The repo `redpanda-data/documentation` was renamed to `redpanda-data/docs`
some time ago. GitHub follows the redirect transparently when Antora
fetches, but the old URL becomes the cache key, so it can stick around
in build caches and contribute to stale-content issues.

Use the current canonical name to make the playbook clearer and to
invalidate any cached entries keyed on the old name on the next build.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@Feediver1
Feediver1 requested a review from a team as a code owner June 10, 2026 19:14
@netlify

netlify Bot commented Jun 10, 2026

Copy link
Copy Markdown

Deploy Preview for rp-cloud ready!

Name Link
🔨 Latest commit 8e61e4d
🔍 Latest deploy log https://app.netlify.com/projects/rp-cloud/deploys/6a5eb35ca1ee1500082e4956
😎 Deploy Preview https://deploy-preview-615--rp-cloud.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1c5cb883-8c2e-4426-ab7d-a620581f103c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This PR updates the Antora playbook configuration to reference a different upstream documentation repository. The local-antora-playbook.yml file is modified to change the content source URL from https://github.com/redpanda-data/documentation to https://github.com/redpanda-data/docs, altering which repository is pulled for the main documentation content with branches: HEAD.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Possibly related PRs

  • redpanda-data/cloud-docs#328: Both PRs modify local-antora-playbook.yml's site.content.sources entry, adjusting the playbook's documentation source configuration.
  • redpanda-data/cloud-docs#610: Both PRs modify local-antora-playbook.yml's Antora content source settings for the documentation repository.
  • redpanda-data/cloud-docs#530: Both PRs modify local-antora-playbook.yml to update the Antora content source configuration for local docs builds.

Suggested reviewers

  • micheleRP
  • JakeSCahill
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description provides comprehensive context including rationale, references to related issues, and clear explanation of the cache key problem, but lacks the required template sections (issue link, page previews, and checks). Add the missing template sections: link to the GitHub issue being resolved, page preview links (if applicable), and check the relevant checkbox from the provided list.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: updating a docs repository URL in the playbook configuration.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix-stale-docs-repo-url

Comment @coderabbitai help to get the list of available commands.

@Feediver1

Copy link
Copy Markdown
Contributor Author

Re-validated 2026-07-20: still valid, still necessary — now the last straggler

Six weeks on, checked whether this one-liner is still worth merging. It is:

Not superseded. cloud-docs main still has the old URL today (local-antora-playbook.yml:17redpanda-data/documentation); nothing merged since June touched it. The PR remains MERGEABLE with no conflicts — blocked only on review.

The premise holds, with fresh evidence. The old URL still resolves (GitHub's rename redirect is alive — verified via ls-remote), so nothing is broken today. But the attribution drift this PR describes is empirically visible: a local cloud-docs Antora build on 2026-07-16 produced 19 occurrences of redpanda-data/documentation as the source attribution on build warnings.

New argument since this PR opened: the production playbook (docs-site/antora-playbook.yml:75) already uses redpanda-data/docs. That makes this local playbook the only one in the fleet still on the old name — local/preview builds attribute shared content to a different repo name than production builds, exactly the kind of inconsistency that has cost this team debugging time in past cache-staleness hunts.

Scope check: this playbook line is the only functional occurrence of the old URL in cloud-docs. The other grep hits are fine as-is: @redpanda-data/documentation in CODEOWNERS is a GitHub team name, and the issue/PR templates reference the old repo's issue tracker and documentation-private — separate concerns.

Residual risk of not merging: GitHub rename redirects die if a new repo ever takes the old name — unlikely, but it would turn this hygiene item into an outage retroactively.

One line, zero risk, aligns local with production. Just needs an approval.

🤖 Generated with Claude Code

@Feediver1
Feediver1 requested a review from JakeSCahill July 20, 2026 23:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant