Skip to content

docs: correct outdated Nightly contributor guide content - #2784

Merged
killme2008 merged 14 commits into
mainfrom
codex/audit-contributor-guide-links
Sep 2, 2026
Merged

docs: correct outdated Nightly contributor guide content#2784
killme2008 merged 14 commits into
mainfrom
codex/audit-contributor-guide-links

Conversation

@killme2008

@killme2008 killme2008 commented Aug 25, 2026

Copy link
Copy Markdown
Member

What changed

Correct and complete the Nightly contributor guide while keeping it focused on component contracts, main execution paths, and contributor decisions rather than source navigation.

  • Replace the early Metasrv design draft and speculative proto examples with current metadata, procedure, leader-election, heartbeat, failover, control-path, and table-route concepts.
  • Explain both Flownode execution paths: batching is the primary path for aggregation and TQL workloads; streaming is retained for compatibility and deprecated for new workloads.
  • Clarify Frontend request paths, Datanode Region dispatch, Mito WAL recovery boundaries, query planning and execution, partition routing and conservative pruning, and the conditional creation of Puffin index files.
  • Turn the testing pages into a test-selection guide covering package tests, Sqlness, integration tests, compatibility tests, and result review.
  • Document the current gRPC ingester contract: generated stubs, request representations, success and error metadata, bounded retries, and ambiguous delivery for unary and streaming writes.
  • Add the missing Metasrv node-lease, recovery, and table-ID sequence endpoints, including their operational constraints.
  • Use the official Apache Parquet file-layout diagram and identify its source.
  • Keep the default selector recommendation, intentional overview links, and DeepWiki as a labeled secondary reference.
  • Remove the obsolete Python Scripts pages after the implementation was removed.
  • Tighten a small number of inflated or awkward sentences without expanding their technical scope.

The architecture and testing boundary follows established contributor documentation practice: explain abstractions, flows, invariants, and how to validate a change; leave implementation-level exploration to the source. No source directory or file-path navigation is added to the architecture pages.

Scope

  • Documentation versions: Nightly, v1.2, v1.1, and v1.0. Each released version was gated on what that
    GreptimeDB release actually ships:
    • v1.2 (v1.2.0-beta.2) takes the change unchanged.
    • v1.1 (v1.1.4) drops the compatibility-test entry (tests/compatibility and cargo sqlness compat
      landed after that release) and x-greptime-err-retry-hint (not sent by v1.1).
    • v1.0 (v1.0.2) additionally omits the new Memtable page, because MemtableOptions there still has a
      PartitionTree variant, so the page's selection rules do not hold; links to it degrade to plain text.
      It also drops the pending-batching-flow sentence (defer_on_missing_source does not exist yet).
    • reference/sql/create.md and the Mito memtable configuration section change only in v1.1 and v1.2.
      v1.0.2 still has MitoConfig::memtable and accepts memtable.type=partition_tree, so the original
      text is correct there.
  • Languages: English, Chinese

Verification

  • DOC_LANG=en pnpm check:links
  • DOC_LANG=zh pnpm check:links
  • typos on all modified Markdown files
  • git diff --check
  • Verified version-sensitive claims against GreptimeDB main at 0cc83c4570, the current greptime-proto
    definitions, and tags v1.0.2, v1.1.4, and v1.2.0-beta.2 for the backported versions.
  • Reviewed the complete diff relative to main; no released/0.x docs, generated outputs, or lockfiles changed. Two user-guide edits are intentional and in scope: user-guide/deployments-administration/configuration.md drops the removed [region_engine.mito.memtable] section, and reference/sql/create.md corrects the memtable.type values.

Checklist

  • I verified the content against the applicable GreptimeDB version.
  • I updated the relevant documentation versions and languages, or explained why not.
  • I checked changed links and anchors.
  • I updated navigation when the document structure changed. sidebars.ts adds the new Memtable page. The removed Python Scripts pages needed no navigation change because they were already excluded from the build.

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Aug 25, 2026

Copy link
Copy Markdown

Deploying greptime-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: e499e61
Status: ✅  Deploy successful!
Preview URL: https://00896b6c.greptime-docs.pages.dev
Branch Preview URL: https://codex-audit-contributor-guid.greptime-docs.pages.dev

View logs

@killme2008 killme2008 changed the title docs: refresh Nightly contributor guide docs: correct outdated Nightly contributor guide content Aug 25, 2026
Comment thread docs/contributor-guide/flownode/dataflow.md
Comment thread docs/contributor-guide/metasrv/admin-api.md
Comment thread docs/contributor-guide/metasrv/overview.md
@killme2008
killme2008 marked this pull request as ready for review August 28, 2026 06:29
Comment thread docs/contributor-guide/metasrv/overview.md Outdated
Comment thread docs/contributor-guide/metasrv/admin-api.md Outdated
@killme2008
killme2008 force-pushed the codex/audit-contributor-guide-links branch from ca9f14d to 1be0a8f Compare August 28, 2026 07:17
Comment thread docs/contributor-guide/datanode/memtable.md
Comment thread docs/contributor-guide/flownode/dataflow.md Outdated

@WenyXu WenyXu left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

These comments clarify two Metasrv contracts that contributors must preserve: cache-invalidation fan-out and the separation between lease renewal and Region failure detection.

Comment thread docs/contributor-guide/metasrv/overview.md Outdated
Comment thread docs/contributor-guide/metasrv/overview.md Outdated
@killme2008

killme2008 commented Sep 2, 2026

Copy link
Copy Markdown
Member Author

f677db3d also contains four self-review fixes outside the commented lines:

  • contributor-guide/overview.md: the previous sentence sent readers to CONTRIBUTING.md for build instructions, but that file has no prerequisites, toolchain, or build commands — the build guide is this repo's own Getting Started page. It now links Getting Started for building and scopes CONTRIBUTING.md to submission requirements.
  • getting-started.md: restored Git (optional) and the 16GB/mold note. The build uses the git2 crate and open_repository tolerates a missing repository, so the git CLI is only needed to clone; the memory/mold guidance is still valid and has no replacement elsewhere.
  • datanode/metric-engine.md: restored the indirect-routing paragraph. LogicalTableRouteValue still stores only physical_table_id, so migrating a physical Region rewrites one physical route instead of every logical route. That is a current invariant, not design rationale.
  • PR description: corrected two statements that did not match the diff — user-guide/.../configuration.md and reference/sql/create.md are changed, and sidebars.ts adds the new Memtable page.

DOC_LANG=en pnpm check:links, DOC_LANG=zh pnpm check:links, and git diff --check all pass.

One item is deliberately left out of this PR: versioned_docs/version-1.1 and version-1.2 (and their Chinese pages) still document [region_engine.mito.memtable] and memtable.type = partition_tree. PartitionTreeMemtable was removed in greptimedb 7840aa1bb4, which shipped in v1.1.0, and unknown config keys are silently dropped, so a user following the v1.2 configuration page gets no error and no effect. Both released versions already have sst_format, so the Nightly wording backports cleanly. I will run the backport once this PR is approved.

@killme2008
killme2008 force-pushed the codex/audit-contributor-guide-links branch from 54bbf18 to bc05f67 Compare September 2, 2026 03:09
.mcp.json must stay at the repository root for the MCP client to read it,
and it holds connection credentials, so ignore it rather than relocate it.
@killme2008
killme2008 force-pushed the codex/audit-contributor-guide-links branch from f3c6e74 to ca0cd4e Compare September 2, 2026 03:31
Comment thread docs/contributor-guide/datanode/memtable.md
Collapse the legacy TimeSeriesMemtable and SimpleBulkMemtable into one
paragraph instead of giving them a selection-table row each and their own
section. They remain reachable for regions on the legacy primary_key SST
format, so the page still names them, but the bulk and flat path is now
clearly the subject.
Apply the Nightly contributor-guide rewrite to the three supported released
versions, and gate each version-sensitive claim on what that release ships.

v1.2 (GreptimeDB v1.2.0-beta.2) takes the change unchanged.

v1.1 (v1.1.4) drops the compatibility-test entry, because tests/compatibility
and 'cargo sqlness compat' arrived after that release, and drops
x-greptime-err-retry-hint, which v1.1 does not send.

v1.0 (v1.0.2) additionally omits the new Memtable page: MemtableOptions there
still has a PartitionTree variant, so the page's selection rules and its
statement that partition_tree is not a third implementation do not hold. The
links to that page degrade to plain text. It also drops the pending-batching-flow
sentence, since defer_on_missing_source does not exist yet, and keeps its own
existing wording where the rewrite did not change meaning.

reference/sql/create.md and the Mito memtable configuration section change only
in v1.1 and v1.2. v1.0.2 still has MitoConfig::memtable and accepts
memtable.type=partition_tree, so the original text is correct there.

Also fix the blog link domain on the new Memtable page: Chinese pages use
greptime.cn and English pages use greptime.com without the www prefix, matching
the existing link to the same article in features-that-you-concern.md.
@killme2008
killme2008 merged commit a730020 into main Sep 2, 2026
8 checks passed
@killme2008
killme2008 deleted the codex/audit-contributor-guide-links branch September 2, 2026 13:40
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.

4 participants