Skip to content

docs(L1): add goquarkchain bugfix retro + lock call-chain docs#153

Open
ping-ke wants to merge 1 commit into
mainfrom
docs/goquarkchain-bugfix-retro
Open

docs(L1): add goquarkchain bugfix retro + lock call-chain docs#153
ping-ke wants to merge 1 commit into
mainfrom
docs/goquarkchain-bugfix-retro

Conversation

@ping-ke

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

Copy link
Copy Markdown
Contributor

Summary

Adds four documents to pm/L1, distilling three weeks (2026-06-14 ~ 07-05) of goquarkchain bug-fix work into reusable guidance for goshard's design and development. goquarkchain is being deprecated, so the goal is to capture root causes and process lessons rather than let the effort stop at "it's fixed."

Two of these (retro + locking) are provided in both Chinese and English.

Files

  • L1/goquarkchain-bugfix-retro.md — three-week bug-fix retrospective (Chinese)
  • L1/goquarkchain-bugfix-retro.en.md — same, English
  • L1/locking.mdMinorBlockChain lock call-chain reference (Chinese)
  • L1/locking.en.md — same, English

What the retrospective covers

  • The incident storyline: how 6~7 individually non-fatal bugs stacked into a self-perpetuating deadlock loop that survived crash-restart (root race between AddBlock and AddRootBlock, typed-nil panic, marker/body inconsistency, sync batch abandonment, etc.).
  • Bug branch inventory: each fix branch / PR, its type, and status.
  • Pitfalls working with AI: the recurring failure modes (keeps getting more complex, reverts on test failure instead of understanding it, doesn't recognize existing changes, carries a flawed premise all the way through) and the countermeasures.
  • Why it took so long: repeated modification, AI-interaction cost, and the slow "run node + watch logs" verification loop.
  • Ten takeaways for goshard: seven technical design principles (reuse Geth, no out-of-lock patch-up writes, lock-vs-performance balance, deterministic race tests, define locks before use, separate local vs global semantics, validate length prefixes before allocating) plus three process/collaboration ones (frame scope/premises/structure up front, commit in small steps, engineering constraints for AI-assisted work).
  • Direct value to goshard: much of goshard is copied from goquarkchain — especially the QuarkChain-specific, Geth-referenceless logic that was this bug chain's disaster area — so these fixes harden the very code goshard reuses.

Move the goquarkchain three-week bugfix retrospective (zh + en) and the
MinorBlockChain lock call-chain reference (zh + en) into pm/L1, the main
docs branch. Fix cross-directory links: ../locking.md -> ./locking.md;
the incident doc link now points to the goquarkchain repo's
fix/sync-unknown-ancestor branch (not mirrored into pm).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.

1 participant