Docs: move internal-only docs out of published docs trees#2414
Docs: move internal-only docs out of published docs trees#2414
Conversation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughDocumentation links were updated to point from Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 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 |
justin808
added
docs-cleanup
Greptile SummaryThis PR reorganizes internal documentation by moving contributor-info and planning docs from published Key changes:
Uncovered references:
Confidence Score: 4/5
Important Files Changed
Last reviewed commit: 19ff55d |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| - React on Rails has taken the hard work out of figuring out the JavaScript tooling that works best with Rails. Not only could you spend lots of time researching different tooling, but then you'd have to figure out how to splice it all together. This is where a lot of "JavaScript fatigue" comes from. The following keep the code clean and consistent: | ||
| - [Style Guide](./style.md) | ||
| - [linters](../contributor-info/linters.md) | ||
| - [linters](./style.md) |
There was a problem hiding this comment.
Changed from linking to ../contributor-info/linters.md (detailed contributor guide with autofix instructions) to ./style.md (high-level style guide). Verify this redirect is intentional for user-facing docs.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/misc/doctrine.md`:
- Line 33: Remove the duplicate "linters" link from docs/misc/doctrine.md by
deleting the line that reads "[linters](./style.md)"; ensure the surrounding
list still renders correctly and that no other references to linters.md are
added in public docs (the internal file was moved to internal/contributor-info/
and should not be linked).
justin808
force-pushed
the
codex/internal-docs-rehome
branch
from
2ff9454 to
eef5d85
Compare
PR Review: Docs ReorganizationThe structural intent of this PR is solid — separating internal contributor docs from user-facing published docs is the right call. The Bug: Broken link in
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| - React on Rails has taken the hard work out of figuring out the JavaScript tooling that works best with Rails. Not only could you spend lots of time researching different tooling, but then you'd have to figure out how to splice it all together. This is where a lot of "JavaScript fatigue" comes from. The following keep the code clean and consistent: | ||
| - [Style Guide](./style.md) | ||
| - [linters](../contributor-info/linters.md) | ||
| - [linters](./style.md) |
There was a problem hiding this comment.
This link is broken. The old path ../contributor-info/linters.md was relative from docs/misc/ to docs/contributor-info/linters.md. Now that the file moved to internal/contributor-info/linters.md, the correct relative path from docs/misc/ is two levels up then into internal/:
| - [linters](./style.md) | |
| - [linters](../../internal/contributor-info/linters.md) |
The current change (./style.md) points to the Style Guide file, duplicating the bullet above it.
There was a problem hiding this comment.
♻️ Duplicate comments (1)
docs/misc/doctrine.md (1)
33-33:⚠️ Potential issue | 🟡 MinorRemove the duplicated
lintersentry.This now points to the same target as
Style Guideon Line 32, so the list renders two different labels for one document. Given this PR’s goal of moving internal-only docs out of published docs, it’s cleaner to drop thelintersline instead of aliasing it tostyle.md.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/misc/doctrine.md` at line 33, Remove the duplicated list entry that reads "linters" which links to ./style.md (it duplicates the "Style Guide" entry on the previous line); locate the list in doctrine.md and delete the "- [linters](./style.md)" line so the document only references the style guide once.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@docs/misc/doctrine.md`:
- Line 33: Remove the duplicated list entry that reads "linters" which links to
./style.md (it duplicates the "Style Guide" entry on the previous line); locate
the list in doctrine.md and delete the "- [linters](./style.md)" line so the
document only references the style guide once.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 541ccce0-4ce6-49ea-9938-0f9d49329a94
📒 Files selected for processing (24)
CONTRIBUTING.mdSUMMARY.mddocs/misc/doctrine.mdinternal/README.mdinternal/contributor-info/ci-optimization.mdinternal/contributor-info/errors-with-hooks.mdinternal/contributor-info/generator-testing.mdinternal/contributor-info/linters.mdinternal/contributor-info/pull-requests.mdinternal/contributor-info/rbs-type-signatures.mdinternal/contributor-info/releasing.mdinternal/planning/DOCS_PR_SUMMARY.mdinternal/planning/DOCUMENTATION_IMPROVEMENT_PLAN.mdinternal/planning/docs-improvement/01-problem-analysis.mdinternal/planning/docs-improvement/02-pr-1813-comparison.mdinternal/planning/docs-improvement/04-ia-redesign-plan.mdinternal/planning/docs-improvement/GITHUB_ISSUE_DRAFT.mdinternal/planning/docs-improvement/ia-redesign-live.mdinternal/planning/library-benchmarking.mdinternal/planning/server-functions-implementation/01-initial-plan.mdinternal/react_on_rails_pro/contributors-info/onboarding-customers.mdinternal/react_on_rails_pro/contributors-info/releasing.mdinternal/react_on_rails_pro/contributors-info/style.mdreact_on_rails_pro/CONTRIBUTING.md
🚧 Files skipped from review as they are similar to previous changes (5)
- internal/react_on_rails_pro/contributors-info/releasing.md
- SUMMARY.md
- react_on_rails_pro/CONTRIBUTING.md
- CONTRIBUTING.md
- internal/README.md
The linters.md file was moved to internal/contributor-info/ as part of this PR's reorganization. Rather than redirecting to style.md (creating a duplicate link), remove the line entirely. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Good structural change overall — separating internal process docs from user-facing docs is the right call. The git mv approach preserves history correctly, and internal/README.md explaining placement rules is a helpful addition. Issue 1: Stale reference in AGENTS.md (line 89) AGENTS.md line 89 still documents docs/contributor-info/ as the location for internal contributor docs, but that directory no longer exists. The PR notes this was intentionally deferred to avoid overlapping with PR 2406, but it should be tracked as a follow-up since AGENTS.md is the canonical policy doc and an incorrect path there can confuse contributors and AI agents. Issue 2: Stale references in .claude/docs/analysis/CI_OPTIMIZATION_SUMMARY.md Three references to the old path docs/contributor-info/ci-optimization.md remain in .claude/docs/analysis/CI_OPTIMIZATION_SUMMARY.md (lines 74, 182, 210). These were not updated to internal/contributor-info/ci-optimization.md. Since .claude/docs/ is read by AI agents during task execution, stale paths here can cause confusion. Issue 3: SUMMARY.md links to internal paths SUMMARY.md now lists ./internal/contributor-info/generator-testing.md, ./internal/contributor-info/linters.md, and ./internal/contributor-info/releasing.md under the CONTRIBUTING section. While SUMMARY.md is already deprecated, if any tooling still parses it for the published site, these internal paths could generate broken links. Low risk, but worth verifying no doc-publishing pipeline reads from SUMMARY.md. Minor Observation: The removal of the linters link from docs/misc/doctrine.md without replacement is intentionally correct — the linters doc is internal and should not be linked from a user-facing published doc. Summary: No runtime impact. The reorganization logic is sound. The two stale-path issues (AGENTS.md and .claude/docs/) should be addressed in a follow-up commit. |
| - [Releasing](./docs/contributor-info/releasing.md) | ||
| - [Generator Testing](./internal/contributor-info/generator-testing.md) | ||
| - [Linting](./internal/contributor-info/linters.md) | ||
| - [Releasing](./internal/contributor-info/releasing.md) |
There was a problem hiding this comment.
SUMMARY.md is used as a table of contents file (commonly by GitBook or similar doc tooling). Linking to ./internal/ paths here means the published docs site would reference files that are intentionally excluded from publishing — potentially generating broken links for end users. While the file is marked "OLD DOCS BELOW" and may no longer drive publishing, it's worth verifying that no doc pipeline still reads it.
## Summary - move internal-only docs from published paths into `internal/` - relocate: - `docs/contributor-info/` -> `internal/contributor-info/` - `docs/planning/` -> `internal/planning/` - `react_on_rails_pro/docs/contributors-info/` -> `internal/react_on_rails_pro/contributors-info/` - update contributor/doc index links to new internal paths - add `internal/README.md` documenting placement rules ## Why - keeps user-facing docs clean and publishable - prevents internal process docs from being mixed with end-user docs - reduces confusion for contributors and AI agents ## Scope - docs path relocations via `git mv` - link updates in: - `CONTRIBUTING.md` - `react_on_rails_pro/CONTRIBUTING.md` - `SUMMARY.md` - `docs/misc/doctrine.md` - `internal/react_on_rails_pro/contributors-info/releasing.md` ## Notes - intentionally did **not** edit `AGENTS.md` in this PR to avoid overlap with open PR #2406 - follow-up PR can update AGENTS path guidance once #2406 is settled ## Verification - `git mv` preserves history for moved docs - no runtime code changes <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reorganized internal contributor documentation structure for clearer separation of user-facing vs internal docs. * Updated multiple documentation links to point to the new internal documentation paths. * Added an internal README describing internal docs layout and publishing rules. <!-- end of auto-generated comment: release notes by coderabbit.ai --> <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Docs-only changes that primarily update file paths and links; no runtime or build logic is affected. > > **Overview** > Moves contributor/process documentation references from the published `docs/` tree to the new `internal/` docs area, updating cross-links in `CONTRIBUTING.md`, `SUMMARY.md`, and `react_on_rails_pro/CONTRIBUTING.md` (including CI optimization and release docs). > > Adds `internal/README.md` to define what belongs in `internal/` vs user-facing docs, and adjusts remaining internal doc links (e.g., Pro releasing doc now points at `internal/contributor-info/releasing.md`). > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit eef5d85. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
…upport * origin/master: (38 commits) fix: use env-var-driven ports in Procfile templates to support multiple worktrees (#2539) Fix prettier formatting in auto-bundling doc Docs: Clarify .client/.server suffixes vs use client RSC directive (#2406) Warn against using .server/.client variants with RSC features Docs: move internal-only docs out of published docs trees (#2414) Fix crash when HTTPX::ErrorResponse is returned in get_form_body_for_file (#2532) Skip flaky external URLs in lychee checks (#2547) Update mise docs: prefer shell-level shims over conductor-exec (#2537) Document compression middleware compatibility with streaming SSR (#2544) Fix duplicate node-renderer message reporting in render failures (#2531) Fix private_output_path not configured on fresh Shakapacker installs (#2289) Bump the npm-security group across 1 directory with 3 updates (#2387) docs: use https links (#2518) Consolidate changelog to keep only rc6 prerelease (#2533) Fix CSS module class name divergence with rspack SSR (#2489) Bump version to 16.4.0.rc.6 Add BugBot license scanning config (#2515) Fix buildVM promise cleanup ordering (#2483) (#2484) Fix streaming SSR hangs and silent error absorption in RSC payload injection (#2407) Ensure lefthook uses mise tools in non-interactive shells (#2512) ... # Conflicts: # CHANGELOG.md
## Summary - Add changelog entries for 6 user-visible PRs merged since v16.4.0.rc.6 that were missing from `[Unreleased]` - Update existing #2561 entry to include #2568 contributor credit ### New entries added | Section | PR | Description | |---|---|---| | Added | #2539 | Environment-variable-driven ports in Procfile templates | | Fixed | #2417 | Rspack generator config path fix | | Fixed | #2419 | Precompile hook load-based execution fix | | Fixed | #2577 | `create-react-on-rails-app` validation improvements | | Pro Fixed | #2416 | StreamResponse status fallback fix | | Pro Fixed | #2566 | Empty-string license plan mismatch fix | ### Skipped PRs (not user-visible) Docs (#2406, #2414, #2479, #2494, #2518, #2537, #2544), CI/internal (#2533, #2547, #2555, #2557, #2558, #2564), dependabot (#2387, #2541), dev dependencies (#2559, #2569, #2573). ## Test plan - [ ] Verify changelog formatting matches existing entries - [ ] Verify all user-visible PRs since v16.4.0.rc.6 are covered 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Documentation-only changelog updates with no runtime or build behavior changes. > > **Overview** > Updates `CHANGELOG.md`’s **[Unreleased]** section to include previously missing user-facing entries: Procfile templates now support env-driven ports, several generator/`bin/dev` precompile-hook and rspack-path fixes are documented, and `create-react-on-rails-app` validation improvements are noted. > > Also adds two Pro fix entries (StreamResponse status fallback and license plan empty-string validation) and updates the existing `bin/dev` precompile-hook entry to credit an additional PR/contributor. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit e75d2b5. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary - Move all OSS documentation from `docs/` root into `docs/oss/`, creating a clean sibling structure with `docs/pro/` (already consolidated by #2556) - Move planning docs (`MONOREPO_MERGER_PLAN.md`, etc.) and testimonials to `internal/` (extends #2414's pattern) - Rewrite `docs/README.md` as a unified entry point with clear navigation to both OSS and Pro docs - Update all cross-references across the codebase: `README.md`, `AGENTS.md`, `CHANGELOG.md`, `NEWS.md`, Ruby source files, generator templates, and spec initializers ### New structure ``` docs/ README.md # Unified entry point oss/ # Open-source docs (9 subdirectories) getting-started/ core-concepts/ building-features/ configuration/ api-reference/ deployment/ upgrading/ migrating/ misc/ introduction.md pro/ # Pro docs (already here from #2556) installation.md configuration.md node-renderer/ react-server-components/ ... ``` Closes #2583 ## Test plan - [ ] Verify all markdown relative links resolve correctly on GitHub - [ ] Spot-check that internal links between OSS docs still work (they use relative `./` and `../` within the preserved subdirectory structure) - [ ] Spot-check Pro→OSS cross-references (`docs/pro/caching.md` → `../oss/core-concepts/...`) - [ ] Coordinate website URL updates in the `sc-website` repo (companion task) - [ ] Run `bundle exec rubocop` on changed Ruby files (done, passing) 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Documentation and link updates only; no behavioral changes beyond updated help text URLs and doc navigation paths. > > **Overview** > Moves the open-source documentation tree under `docs/oss/` to cleanly separate it from the existing `docs/pro/` docs, and rewrites `docs/README.md` to act as a unified navigation landing page for both OSS and Pro. > > Updates doc links across repository-facing files (`README.md`, `NEWS.md`, `CHANGELOG.md`, `AGENTS.md`) and in-code pointers (generator initializer template, `react_on_rails:doctor` output, `TestHelper` comment, dummy app initializers, and a few Pro docs) to reference the new `docs/oss/...` paths. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 77c3d67. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reorganized site to explicitly separate Open Source (OSS) and Pro documentation hierarchies. * Migrated OSS content under an OSS docs subtree and updated links across README, changelog, NEWS, and many guides. * Introduced a distinct Pro pathway and adjusted cross‑links between OSS and Pro content and examples. * Expanded Troubleshooting and Pro guidance (node renderer, caching, RSC, error reporting) and corrected numerous relative link targets. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
1 participant
Summary
internal/docs/contributor-info/->internal/contributor-info/docs/planning/->internal/planning/react_on_rails_pro/docs/contributors-info/->internal/react_on_rails_pro/contributors-info/internal/README.mddocumenting placement rulesWhy
Scope
git mvCONTRIBUTING.mdreact_on_rails_pro/CONTRIBUTING.mdSUMMARY.mddocs/misc/doctrine.mdinternal/react_on_rails_pro/contributors-info/releasing.mdNotes
AGENTS.mdin this PR to avoid overlap with open PR Docs: Clarify .client/.server suffixes vs 'use client' RSC directive #2406Verification
git mvpreserves history for moved docsSummary by CodeRabbit
Note
Low Risk
Docs-only changes that primarily update file paths and links; no runtime or build logic is affected.
Overview
Moves contributor/process documentation references from the published
docs/tree to the newinternal/docs area, updating cross-links inCONTRIBUTING.md,SUMMARY.md, andreact_on_rails_pro/CONTRIBUTING.md(including CI optimization and release docs).Adds
internal/README.mdto define what belongs ininternal/vs user-facing docs, and adjusts remaining internal doc links (e.g., Pro releasing doc now points atinternal/contributor-info/releasing.md).Written by Cursor Bugbot for commit eef5d85. Configure here.