Reorganize docs into Tools & APIs, Configuration, and Internals groups#288
Reorganize docs into Tools & APIs, Configuration, and Internals groups#288hackerwins merged 1 commit intomainfrom
Conversation
Split the navigation into clearer groups: - Tools & APIs (order 60): Devtools, CLI, Admin API, MCP - Configuration (order 110): Architecture Patterns, Security, Event Webhook, Revisions, Resources, Projects - Internals (order 120): CRDT Concepts, Synchronization, Document Lifecycle, YSON, Cluster Mode Also adds new pages (Projects, CRDT Concepts, Synchronization, Document Lifecycle, Cluster Mode) and enriches the Glossary with additional terms and cross-links. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThis pull request reorganizes the documentation structure by creating a new "Internals" section for internal CRDT concepts and moving tool references to a dedicated "Tools & APIs" section. Multiple documentation files are updated with revised link paths to reflect this reorganization. A new "Projects" page is added to the Configuration section. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 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 |
![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
🤖 Fix all issues with AI agents
In `@docs/internals/cluster-mode.mdx`:
- Around line 86-102: Update the DestinationRule manifest to use the stable API
version by replacing apiVersion: networking.istio.io/v1alpha3 with apiVersion:
networking.istio.io/v1 in the YAML snippet that defines the DestinationRule
named yorkie; keep the rest of the spec (host, trafficPolicy, portLevelSettings,
consistentHash/ringHash/httpHeaderName) unchanged so the consistentHash
structure remains compliant with the Istio spec.
In `@docs/internals/synchronization.mdx`:
- Around line 128-131: The sentence currently implies Garbage Collection uses
Checkpoints to decide when tombstoned nodes can be removed; reword it to state
that GC relies on Version Vectors (minVersionVector) to determine safe removal
and that Checkpoints (ServerSeq/ClientSeq) only track sync progress and
indirectly support GC by ensuring clients catch up and update their version
vectors; reference the terms "Checkpoint", "ServerSeq", "ClientSeq", "Version
Vectors", and "minVersionVector" and replace the existing sentence with a
concise line clarifying this distinction (or add a short clarifying clause) so
the relationship between checkpoints and GC is precise.
🧹 Nitpick comments (5)
docs/index.mdx (1)
40-40: Consider linking to the new dedicated Projects page instead of the CLI anchor.This sentence explains the concept of Projects ("organize multiple independent applications within a single Yorkie installation"), which aligns better with the new
/docs/advanced/projectspage. The CLI anchor (/docs/tools/cli#project) is more about the CLI commands for managing projects.Suggested change
-Additionally, **[Projects](/docs/tools/cli#project)** allow you to organize multiple independent applications within a single Yorkie installation, each with its own documents, channels, and clients. Learn more about key concepts in the [Glossary](/docs/glossary). +Additionally, **[Projects](/docs/advanced/projects)** allow you to organize multiple independent applications within a single Yorkie installation, each with its own documents, channels, and clients. Learn more about key concepts in the [Glossary](/docs/glossary).docs/internals/document-lifecycle.mdx (2)
47-53: Nit:Removedstate's "Allowed Operations" column is misleading.Line 53 lists
deactivate()as the allowed operation for theRemovedstate, butdeactivate()is a client-level operation, not a document-level one. Listing it here implies there's a document-level action you can still take on a removed document. Consider either clarifying this (e.g., "None (client can stilldeactivate())") or listing "None" to avoid confusion.
113-123: Missing import forDocStatusin the code example.The snippet uses
DocStatus.Attached,DocStatus.Detached, andDocStatus.Removedbut never shows whereDocStatusis imported from. Adding the import would make the example copy-paste friendly.Suggested fix
+import { DocStatus } from '@yorkie-js/sdk'; + doc.subscribe('status', (event) => {docs/internals/synchronization.mdx (2)
163-170: Snapshot event subscription uses different API pattern than other examples.This example uses
doc.subscribe((event) => { if (event.type === 'snapshot') ... })(no topic argument), while the Document Status Events example indocument-lifecycle.mdxusesdoc.subscribe('status', (event) => ...)(with a topic string). Both patterns may be valid in the SDK, but it would be helpful to add a brief note or use the topic-based formdoc.subscribe('snapshot', ...)if it exists, for consistency across the new docs.
231-244: Document compaction: "not currently attached to any client" is a strong precondition.This is good to document explicitly. It means compaction can only run on "cold" documents. For production users, this is a key operational detail — if a document is always attached by at least one client, it will never be compacted. Consider adding a brief note about this implication.
| ```yaml | ||
| apiVersion: networking.istio.io/v1alpha3 | ||
| kind: DestinationRule | ||
| metadata: | ||
| name: yorkie | ||
| spec: | ||
| host: yorkie | ||
| trafficPolicy: | ||
| portLevelSettings: | ||
| - port: | ||
| number: 8080 | ||
| loadBalancer: | ||
| consistentHash: | ||
| ringHash: | ||
| minimumRingSize: 1024 | ||
| httpHeaderName: "x-shard-key" | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Istio DestinationRule API version v1 vs v1alpha3 current 2024 2025
💡 Result:
- What changed (2024): Starting with Istio 1.22 (May 13, 2024),
DestinationRulewas promoted toapiVersion: networking.istio.io/v1(along with several other networking APIs).v1beta1andv1alpha3remained supported, but Istio encouraged users to move tov1. [1] - What to use in 2024–2025: For current Istio docs and examples,
DestinationRuleis shown asnetworking.istio.io/v1. [2] - Is
v1alpha3still valid? Yes—Istio’s v1-APIs announcement explicitly listsDestinationRuleas available inv1,v1beta1, andv1alpha3, and states there were no plans (at that time) to discontinue older versions, though migration tov1is recommended. [1] - Important nuance (1.23+): Istio 1.23 (Aug 14, 2024) consolidated internal protobuf/API definitions, but for Kubernetes YAML usage there is “no impact”—so using
v1vs older versions is mainly about using the stable API version rather than changing the schema. [3]
Practical guidance:
- New manifests (2024/2025+): use
apiVersion: networking.istio.io/v1. [1][2] - Existing
v1alpha3manifests: typically still apply, but plan to migrate tov1for “stable API” posture. [1]
Sources: [1] Istio blog: “Introducing Istio v1 APIs” (May 13, 2024); [2] Istio DestinationRule reference (shows networking.istio.io/v1); [3] Istio 1.23 upgrade notes (Aug 14, 2024).
🌐 Web query:
Istio consistentHash ringHash httpHeaderName field structure documentation
💡 Result:
In Istio DestinationRule, the structure is:
-
spec.trafficPolicy.loadBalancer.consistentHashis a oneof that can hash on exactly one of:httpHeaderName: <header>(string)httpCookie: { name: <cookie>, ttl: <duration>, path: <path> }httpQueryParameterName: <param>(string)useSourceIp: true(bool)
-
Optional consistent-hash algorithm tuning is configured alongside (as siblings of)
httpHeaderNameetc.:ringHash: { minimumRingSize: <uint64> }maglev: { tableSize: <uint64> }(preliminary.istio.io)
Example (header-hash + ring-hash settings):
apiVersion: networking.istio.io/v1
kind: DestinationRule
metadata:
name: my-svc
spec:
host: my-svc.default.svc.cluster.local
trafficPolicy:
loadBalancer:
consistentHash:
httpHeaderName: x-user-id
ringHash:
minimumRingSize: 1024Reference: Istio DestinationRule API docs → LoadBalancerSettings.ConsistentHashLB and RingHash. (preliminary.istio.io)
Citations:
- 1: https://preliminary.istio.io/latest/docs/reference/config/networking/destination-rule/?utm_source=openai
- 2: https://preliminary.istio.io/latest/docs/reference/config/networking/destination-rule/?utm_source=openai
Update Istio DestinationRule API version to v1.
The documentation uses apiVersion: networking.istio.io/v1alpha3, which is outdated. Starting with Istio 1.22 (May 2024), DestinationRule was promoted to networking.istio.io/v1. While v1alpha3 remains supported, current Istio documentation and examples use v1. Update the snippet to use networking.istio.io/v1 to reflect the stable API version.
The consistentHash field structure (with ringHash and httpHeaderName as siblings) is correct per the Istio spec.
🤖 Prompt for AI Agents
In `@docs/internals/cluster-mode.mdx` around lines 86 - 102, Update the
DestinationRule manifest to use the stable API version by replacing apiVersion:
networking.istio.io/v1alpha3 with apiVersion: networking.istio.io/v1 in the YAML
snippet that defines the DestinationRule named yorkie; keep the rest of the spec
(host, trafficPolicy, portLevelSettings, consistentHash/ringHash/httpHeaderName)
unchanged so the consistentHash structure remains compliant with the Istio spec.
| ``` | ||
|
|
||
| Checkpoints are also used by [Garbage Collection](/docs/internals/crdt-concepts#garbage-collection) to determine when tombstoned nodes can be safely removed -- only after all clients have synced past the version where the node was deleted. | ||
|
|
There was a problem hiding this comment.
Checkpoint–GC relationship is slightly imprecise.
Line 130 states checkpoints are used by Garbage Collection to determine when tombstoned nodes can be removed. However, per the CRDT Concepts page (also added in this PR), GC uses Version Vectors (minVersionVector), not Checkpoints (ServerSeq/ClientSeq). Checkpoints track sync progress, while version vectors track causality.
Consider rewording to avoid conflating the two mechanisms, or clarifying that checkpoints indirectly support GC by ensuring clients have synced (which updates their version vectors).
Suggested rewording
-Checkpoints are also used by [Garbage Collection](/docs/internals/crdt-concepts#garbage-collection) to determine when tombstoned nodes can be safely removed -- only after all clients have synced past the version where the node was deleted.
+Checkpoints support [Garbage Collection](/docs/internals/crdt-concepts#garbage-collection) indirectly -- by tracking sync progress, the system ensures clients' [Version Vectors](/docs/internals/crdt-concepts#version-vectors) are up to date, which determines when tombstoned nodes can be safely removed.📝 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.
| ``` | |
| Checkpoints are also used by [Garbage Collection](/docs/internals/crdt-concepts#garbage-collection) to determine when tombstoned nodes can be safely removed -- only after all clients have synced past the version where the node was deleted. |
🤖 Prompt for AI Agents
In `@docs/internals/synchronization.mdx` around lines 128 - 131, The sentence
currently implies Garbage Collection uses Checkpoints to decide when tombstoned
nodes can be removed; reword it to state that GC relies on Version Vectors
(minVersionVector) to determine safe removal and that Checkpoints
(ServerSeq/ClientSeq) only track sync progress and indirectly support GC by
ensuring clients catch up and update their version vectors; reference the terms
"Checkpoint", "ServerSeq", "ClientSeq", "Version Vectors", and
"minVersionVector" and replace the existing sentence with a concise line
clarifying this distinction (or add a short clarifying clause) so the
relationship between checkpoints and GC is precise.
1 participant
What this PR does / why we need it?
Reorganize docs into Tools & APIs, Configuration, and Internals groups
Split the navigation into clearer groups:
Also adds new pages (Projects, CRDT Concepts, Synchronization, Document Lifecycle, Cluster Mode) and enriches the Glossary with additional terms and cross-links.
Any background context you want to provide?
What are the relevant tickets?
Fixes #
Checklist
Summary by CodeRabbit
Documentation