Skip to content

docs(L1): add minor block commit-status fix review doc#157

Open
ping-ke wants to merge 4 commits into
mainfrom
docs/quarkchain-minor-commit-status
Open

docs(L1): add minor block commit-status fix review doc#157
ping-ke wants to merge 4 commits into
mainfrom
docs/quarkchain-minor-commit-status

Conversation

@ping-ke

@ping-ke ping-ke commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

  • Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
  • Approach — three ordered steps, one per PR:
    1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
    2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
    3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
  • Per-PR theme, commits, files, key points, and reviewer focus.
  • Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
  • Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

  • Chinese and English versions are kept in sync; update both together on future edits.

Design/review doc for the goquarkchain minor-block commit-status fix,
split into 3 stacked PRs (head locking / commit-status semantics /
sidechain body anchor). Chinese and English versions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Comment thread L1/quarkchain-fix/minor-commit-status-review.md Outdated
@ping-ke ping-ke requested a review from qzhodl July 13, 2026 17:09
@ping-ke ping-ke changed the title docs(L1): add minor block commit-status fix design & review doc docs(L1): add minor block commit-status fix review doc Jul 14, 2026
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.

2 participants