docs: restructure transaction & checkpoint docs for user-first reading - #1050
docs: restructure transaction & checkpoint docs for user-first reading#1050zhanglei1949 wants to merge 4 commits into
Conversation
- Reorder transaction.mdx: modes/ACID/usage up front, advanced later - Slim checkpoint.md; move internals to new how_it_works.md - Split explicit transactions into explicit_transactions.mdx - Update Nextra (_meta.ts) and Sphinx (index.rst) navigation
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Pull request overview
Restructures the transaction/checkpoint docs to be “user-first” by moving internal details into dedicated pages and splitting explicit-transaction usage into its own document.
Changes:
- Reorganized
transaction.mdxaround deployment modes, ACID guarantees, usage, and best practices; moved historical/design material into an appendix. - Slimmed
checkpoint.mdto user-facing behavior; relocated internal layout/protocol details into a new internal page. - Added new pages for explicit transactions and internal mechanics; updated Nextra + Sphinx navigation.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| doc/source/transaction/transaction.mdx | Major rewrite/reorder; adds ACID + usage-first structure and points to new dedicated pages. |
| doc/source/transaction/how_it_works.md | New internal-mechanics page (COW/MVCC, on-disk layout, checkpoint protocol, GC, v1 migration). |
| doc/source/transaction/explicit_transactions.mdx | New page extracting explicit transaction usage, rules, and per-mode details. |
| doc/source/transaction/checkpoint.md | Removes deep internals; adds link to “How It Works” and keeps operational usage/concurrency/failure guidance. |
| doc/source/transaction/_meta.ts | Adds navigation entries for the two new pages in the transaction section. |
| doc/source/index.rst | Updates Sphinx toctree caption and includes the new transaction docs pages. |
| doc/source/_meta.ts | Renames top-level nav label to “Transaction & Checkpoint”. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation-only, internally consistent across the updated pages, and navigation/link updates appear coherent based on repository references.
Review details
- Files reviewed: 7/7 changed files
- Comments generated: 0 new
- Review effort level: Lite
Summary
Restructure the transaction and checkpoint documentation to be user-first: deployment modes, ACID guarantees, and usage come first; AP/TP specifics, edge cases, and internal mechanisms move later or into dedicated pages.
Changes
_meta.ts) and Sphinx (index.rst); section caption renamed to "Transaction & Checkpoint".Notes
Docs-only; no code affected. All cross-links and anchors verified.