[lucasfang]

Purpose

Linked issue: None.

The guides contain stale cleanup restrictions, incomplete protocol metadata, and snapshot descriptions that assume direct file-system publication. The BLOB schema example also uses an internal macro unavailable in installed headers.

• Replace the internal Arrow conversion macro in the BLOB example with explicit public-API error handling.
• Document pinned metadata-system-table snapshots, catalog publication versus REST request preparation, and catalog-only current snapshots. Align the snapshot JSON reference, including omitted watermarks and optional metadata.
• Correct cleanup support for primary-key tables, index manifests and payloads, tag retention, and optional empty-directory cleanup. Set the documented snapshot.expire.limit default to 50. Keep the restrictions on changelog/statistics cleanup and orphan cleanup of tagged or branched tables.
• Correct binary min/max keys and complete the data-file and index-manifest field lists.
• Explain the experimental real-time append-deduplication exception for updates and deletes.
• Explicitly declare C++17 in the consumer CMake example. Arrow's exported target can already propagate this requirement; this makes the example's requirement explicit.
• Add a prominent local-modification notice to each of the three vendored CRoaring files for the paimon::roaring namespace changes. Preserve every byte of the previous file contents, including all upstream copyright and license notices.

Tests

Passed locally:

• Pre-commit checks on all 12 PR files and git diff --check. Repository configuration excludes vendored files from formatting and C++ lint.
• Doxygen XML generation and the complete Sphinx HTML build with -W --keep-going.
• Rebuilt the roaring_bitmap target.
• 30 focused core tests covering cleanup defaults, primary-key orphan cleanup, index/tag retention, empty directories, data-file metadata and snapshot serialization; 2 real-time update/delete integration tests.
• Extracted the CMake example into a temporary consumer project and built it against an existing installed Paimon package and bundled Arrow 17. The compile command uses -std=gnu++17.
• Compared the documented schemas against the source: 21 data-file fields, 10 index-manifest fields and 22 snapshot JSON fields. Verified that CRoaring changes are exactly the added notice prefix.
• The corrected BLOB example was compiled using public headers only with g++ -std=c++17 -Wall -Werror -fsyntax-only.

Commands for the follow-up validation:

pre-commit run --files \
  docs/source/basic_concepts.rst docs/source/build_system.rst \
  docs/source/user_guide/append_only_table.rst docs/source/user_guide/clean.rst \
  docs/source/user_guide/manifest.rst docs/source/user_guide/snapshot.rst \
  docs/source/user_guide/write.rst docs/source/user_guide/system_tables.rst \
  docs/source/user_guide/commit.rst \
  third_party/roaring_bitmap/roaring.cpp third_party/roaring_bitmap/roaring.h \
  third_party/roaring_bitmap/roaring.hh
cmake --build build --target roaring_bitmap -j 8
(cd apidoc && OUTPUT_DIRECTORY=/tmp/paimon-docs-followup-doxygen doxygen Doxyfile)
PAIMON_CPP_DOXYGEN_XML=/tmp/paimon-docs-followup-doxygen/xml sphinx-build -b html -W --keep-going -j 4 docs/source /tmp/paimon-docs-followup-html
./build/debug/paimon-core-test --gtest_filter='CoreOptionsTest.TestDefaultValue:OrphanFilesCleanerTest.TestPkTable:OrphanFilesCleanerTest.TestTableWithIndexManifest:ExpireSnapshotsTest.TestExpireSourceBackedBTreeIndexFiles:ExpireSnapshotsTest.TestExpireKeepsSourceBackedBTreeIndexReferencedByTag:ExpireSnapshotsTest.TestRetainedStatisticsAreIncludedInManifestSkippingSet:ExpireSnapshotsTest.TestCleansEmptyPartitionHierarchyAndKeepsNonemptyPartition:ExpireSnapshotsTest.TestEmptyUnpartitionedBucketDoesNotDeleteTableDirectory:SnapshotTest.*:DataFileMetaTest.*:IndexManifestEntrySerializerTest.*'
./build/debug/paimon-realtime-write-inte-test --gtest_filter='RealtimeWriteInteTest.TestRealtimeDeduplicateDeletesCommittedKey:RealtimeWriteInteTest.TestRealtimeDeduplicateUpdateBeforeAndAfter'
cmake --build /tmp/paimon-docs-followup-consumer/build --verbose
git diff --check

The core and integration runs use existing binaries; those executables were not rebuilt. Sanitized tests ran outside the sandbox so LeakSanitizer could inspect /proc. No new runtime tests were added, and the full C++ suite was not run. Consumer configuration uses local package prefixes and Arrow_DIR; no source installation was rebuilt for that smoke test.

API and Format

No public API, storage format, protocol or runtime behavior changes. Third-party source changes are comments only.

Documentation

Update the write, commit, system-table, cleanup, append-table, snapshot, manifest, basic-concepts and integration guides to match existing behavior. No new feature is introduced.

Generative AI tooling

Generated-by: OpenAI Codex (codex-cli 0.166.0)

[lxy-9602]

+1