Skip to content

Organize design docs into sheets/ and docs/ subdirectories#107

Merged
hackerwins merged 2 commits into
mainfrom
organize-design-docs
Apr 5, 2026
Merged

Organize design docs into sheets/ and docs/ subdirectories#107
hackerwins merged 2 commits into
mainfrom
organize-design-docs

Conversation

@hackerwins

@hackerwins hackerwins commented Apr 5, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Move 12 sheets-related design docs into docs/design/sheets/
  • Move 14 docs-related design docs into docs/design/docs/
  • Keep 10 common/infrastructure docs flat in docs/design/
  • Update all cross-references (README index, package READMEs, task files)

Test plan

  • pnpm verify:fast passes
  • Verify markdown links render correctly on GitHub

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Reorganized design documentation structure into functional categories (Sheets, Docs, Common).
    • Updated internal documentation references and links to reflect the new organization.
    • No user-facing changes or feature impacts.

docs/design/ had 38 files in a flat structure, making it hard to
navigate. Move sheets-related docs (12 files) into sheets/ and
word-processor-related docs (14 files) into docs/, keeping common
infrastructure docs flat. Update all cross-references in README
index, package READMEs, frontend.md, and task files.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
@coderabbitai

coderabbitai Bot commented Apr 5, 2026

Copy link
Copy Markdown

Warning

Rate limit exceeded

@hackerwins has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 4 minutes and 32 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 4 minutes and 32 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 04f2a2d4-9fcb-43fb-8ea6-76edc70f92bb

📥 Commits

Reviewing files that changed from the base of the PR and between 2369bc3 and 61959a5.

📒 Files selected for processing (6)
  • docs/tasks/archive/2026/03/20260320-docs-package-todo.md
  • docs/tasks/archive/2026/03/20260329-docs-table-selection-todo.md
  • docs/tasks/archive/2026/03/20260329-docs-table-ui-todo.md
  • docs/tasks/archive/2026/03/20260329-docs-tables-todo.md
  • docs/tasks/archive/2026/03/20260329-table-crdt-phase-a-todo.md
  • docs/tasks/archive/2026/03/20260329-table-crdt-phase-b-todo.md
📝 Walkthrough

Walkthrough

This pull request reorganizes design document paths by moving documentation files from docs/design/ into subdirectories (docs/design/docs/ and docs/design/sheets/), then updating all references throughout the codebase to reflect the new locations. The main README is restructured to categorize sections accordingly.

Changes

Cohort / File(s) Summary
Design Documentation Structure
docs/design/README.md
Reorganized top-level categorization from mixed "Documents" section into three grouped sections: "Sheets" (formulas, calculator, charts, pivot tables, conditional formatting, collaboration, data sources), "Docs" (editor topics like tables/CRDT/resize, rendering, pagination, collaboration, remote cursor, mobile zoom-to-fit, intent-preserving edits, ruler), and "Common" (cross-cutting items: frontend/backend, context menu, peer-cursor labels, REST/CLI, auth, harness engineering, homepage, docs-site).
Frontend Design References
docs/design/frontend.md
Updated two design doc link paths: collaboration model and batch transaction references now point to sheets/ subdirectory instead of root design folder.
Active Task Documentation
docs/tasks/active/20260403-intent-preserving-phase*-todo.md
Updated design doc references from docs/design/docs-intent-preserving-edits.md to docs/design/docs/docs-intent-preserving-edits.md (2 files).
Archived Task Documentation
docs/tasks/archive/2026/03/20260314-*.md, 20260320-*.md, 20260321-*.md, 20260322-*.md, 20260323-*.md, 20260324-*.md, 20260326-*.md, 20260328-*.md, 20260329-*.md, 20260331-*.md
docs/tasks/archive/2026/04/20260402-*.md
Updated numerous design doc reference paths to reflect relocation to docs/design/docs/ (for word processor topics) and docs/design/sheets/ (for spreadsheet topics). Pattern: docs/design/{filename}.mddocs/design/docs/{filename}.md or docs/design/sheets/{filename}.md (18 files).
Package Documentation
packages/docs/README.md, packages/sheets/README.md
Updated "Further Reading" links to point to relocated design documents in new subdirectories: docs.md and docs-pagination.md now under docs/ subdirectory; sheet.md now under sheets/ subdirectory.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

Poem

🐰 A rabbit hops through docs with glee,
Reorganizing thoughtfully,
From docs/design/ to subfolders neat,
sheets/ and docs/ paths complete,
All links now point where docs should be! 📚✨

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately and concisely describes the main change: reorganizing design documentation into sheets/ and docs/ subdirectories.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.

✏️ 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 organize-design-docs

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.

❤️ Share

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

@github-actions

github-actions Bot commented Apr 5, 2026

Copy link
Copy Markdown
Contributor

Verification: verify:self

Result: ✅ PASS in 115.9s

Lane Status Duration
sheets:build ✅ pass 14.1s
docs:build ✅ pass 7.3s
verify:fast ✅ pass 57.2s
frontend:build ✅ pass 15.4s
verify:frontend:chunks ✅ pass 0.3s
backend:build ✅ pass 4.5s
cli:build ✅ pass 1.9s
verify:entropy ✅ pass 15.3s

Verification: verify:integration

Result: ✅ PASS

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 7

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/design/frontend.md`:
- Line 254: The PR introduced links pointing at docs/design/sheets (e.g., the
"collaboration.md" link and other references to docs/design/sheets/...), which
conflicts with the repo rule requiring design docs under docs/design/ (pattern
docs/design/**/*.md); fix by either moving the referenced markdown files up to
the flat docs/design/ location and updating the link targets to
docs/design/<topic>.md (ensure links like "collaboration.md" now resolve at
docs/design/collaboration.md) or, if you intentionally want a subdirectory,
update the repository guideline text to allow docs/design/sheets/ and adjust the
documented pattern accordingly so the change is consistent.

In `@docs/tasks/archive/2026/03/20260320-docs-package-todo.md`:
- Line 7: The relative link target "**docs/design/docs/docs.md**" is too shallow
for this archived doc (currently "../../design/docs/docs.md" on line 7); update
the link to back up one more directory (use "../../../design/docs/docs.md") so
the link resolves correctly from docs/tasks/archive/2026/03/; edit the Markdown
link in the file (the line containing "../../design/docs/docs.md") to the
corrected "../../../design/docs/docs.md".

In `@docs/tasks/archive/2026/03/20260329-docs-table-selection-todo.md`:
- Line 11: The markdown spec link "docs/design/docs/docs-tables.md" in
docs/tasks/archive/2026/03/20260329-docs-table-selection-todo.md uses an
incorrect relative path ("../../design/docs/docs-tables.md"); update the link to
traverse one more directory up so it points to
"../../../design/docs/docs-tables.md" to ensure the GitHub link resolves
correctly.

In `@docs/tasks/archive/2026/03/20260329-docs-table-ui-todo.md`:
- Line 11: The relative spec link "../../design/docs/docs-table-ui.md" in the
markdown (the link text in 20260329-docs-table-ui-todo.md) is broken; update
that link target to the correct relative path from this file by replacing
"../../design/docs/docs-table-ui.md" with
"../../../../design/docs/docs-table-ui.md" so it resolves to the
docs/design/docs-table-ui.md spec.

In `@docs/tasks/archive/2026/03/20260329-docs-tables-todo.md`:
- Line 11: The Spec link in the markdown currently points to
../../design/docs/docs-tables.md which is two levels up and wrong from this
file; update the link target to ../../../design/docs/docs-tables.md so the
anchor [docs/design/docs/docs-tables.md] points to the correct location (keep
the link text the same and only change the URL).

In `@docs/tasks/archive/2026/03/20260329-table-crdt-phase-a-todo.md`:
- Line 11: Update the broken relative link in the markdown line that reads
"**Spec:** [docs/design/docs/docs-table-crdt.md]" so it resolves from
docs/tasks/archive/2026/03/; replace "../../design/docs/docs-table-crdt.md" with
a correct path such as "../../../../design/docs/docs-table-crdt.md" or the
repo-root absolute "/design/docs/docs-table-crdt.md" so the Spec link renders
properly on GitHub.

In `@docs/tasks/archive/2026/03/20260329-table-crdt-phase-b-todo.md`:
- Line 11: The relative link "docs/design/docs/docs-table-crdt.md" is too
shallow for this file's folder depth; update the Markdown link target to go up
one more directory (use "../../../design/docs/docs-table-crdt.md") so the
reference from the docs/tasks/archive/2026/03 file resolves correctly; change
the link text target in the line containing
"docs/design/docs/docs-table-crdt.md" accordingly.
🪄 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: 58660355-3e91-4686-acff-ed4937b6a3ee

📥 Commits

Reviewing files that changed from the base of the PR and between 652da59 and 2369bc3.

📒 Files selected for processing (53)
  • docs/design/README.md
  • docs/design/docs/docs-collaboration.md
  • docs/design/docs/docs-frontend-integration.md
  • docs/design/docs/docs-intent-preserving-edits.md
  • docs/design/docs/docs-mobile-zoom-to-fit.md
  • docs/design/docs/docs-pagination.md
  • docs/design/docs/docs-remote-cursor.md
  • docs/design/docs/docs-rendering-optimization.md
  • docs/design/docs/docs-ruler.md
  • docs/design/docs/docs-table-crdt.md
  • docs/design/docs/docs-table-resize.md
  • docs/design/docs/docs-table-ui.md
  • docs/design/docs/docs-tables.md
  • docs/design/docs/docs-wordprocessor-roadmap.md
  • docs/design/docs/docs.md
  • docs/design/frontend.md
  • docs/design/sheets/batch-transactions.md
  • docs/design/sheets/calculator.md
  • docs/design/sheets/charts.md
  • docs/design/sheets/collaboration.md
  • docs/design/sheets/conditional-format-multi-range.md
  • docs/design/sheets/datasource.md
  • docs/design/sheets/formula-coverage.md
  • docs/design/sheets/formula.md
  • docs/design/sheets/pivot-table.md
  • docs/design/sheets/scroll-and-rendering.md
  • docs/design/sheets/sheet-style.md
  • docs/design/sheets/sheet.md
  • docs/tasks/active/20260403-intent-preserving-phase4-table-cells-todo.md
  • docs/tasks/active/20260403-intent-preserving-phase5-undo-redo-todo.md
  • docs/tasks/archive/2026/03/20260314-collaboration-design-docs-todo.md
  • docs/tasks/archive/2026/03/20260314-yorkie-worksheet-shape-migration-todo.md
  • docs/tasks/archive/2026/03/20260320-docs-package-todo.md
  • docs/tasks/archive/2026/03/20260321-cf-multi-range-todo.md
  • docs/tasks/archive/2026/03/20260321-docs-pagination-todo.md
  • docs/tasks/archive/2026/03/20260321-pr58-review-todo.md
  • docs/tasks/archive/2026/03/20260322-docs-collaboration-todo.md
  • docs/tasks/archive/2026/03/20260322-docs-rendering-optimization-todo.md
  • docs/tasks/archive/2026/03/20260323-docs-frontend-integration-todo.md
  • docs/tasks/archive/2026/03/20260323-yorkie-doc-store-todo.md
  • docs/tasks/archive/2026/03/20260324-docs-remote-cursor-todo.md
  • docs/tasks/archive/2026/03/20260326-docs-phase2-todo.md
  • docs/tasks/archive/2026/03/20260328-docs-mobile-zoom-to-fit-todo.md
  • docs/tasks/archive/2026/03/20260329-docs-table-selection-todo.md
  • docs/tasks/archive/2026/03/20260329-docs-table-ui-todo.md
  • docs/tasks/archive/2026/03/20260329-docs-tables-todo.md
  • docs/tasks/archive/2026/03/20260329-table-crdt-phase-a-todo.md
  • docs/tasks/archive/2026/03/20260329-table-crdt-phase-b-todo.md
  • docs/tasks/archive/2026/03/20260329-table-granular-updates-todo.md
  • docs/tasks/archive/2026/03/20260331-table-resize-todo.md
  • docs/tasks/archive/2026/04/20260402-intent-preserving-phase1-3-todo.md
  • packages/docs/README.md
  • packages/sheets/README.md

Comment thread docs/design/frontend.md
Comment thread docs/tasks/archive/2026/03/20260320-docs-package-todo.md Outdated
Comment thread docs/tasks/archive/2026/03/20260329-docs-table-selection-todo.md Outdated
Comment thread docs/tasks/archive/2026/03/20260329-docs-table-ui-todo.md Outdated
Comment thread docs/tasks/archive/2026/03/20260329-docs-tables-todo.md Outdated
Comment thread docs/tasks/archive/2026/03/20260329-table-crdt-phase-a-todo.md Outdated
Comment thread docs/tasks/archive/2026/03/20260329-table-crdt-phase-b-todo.md Outdated
The markdown links used ../../design/ but the files are 5 levels
deep (docs/tasks/archive/2026/03/), so the correct relative path
is ../../../../design/.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
@hackerwins
hackerwins merged commit e5dcf66 into main Apr 5, 2026
3 checks passed
@hackerwins
hackerwins deleted the organize-design-docs branch April 5, 2026 11:31
@hackerwins hackerwins mentioned this pull request Apr 11, 2026
4 tasks
@coderabbitai coderabbitai Bot mentioned this pull request Apr 19, 2026
12 tasks
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