Skip to content

docs: fold reference/ into feature/, split offset-lb-frame into three EN pages, rewrite redesign.md in English - #5391

Merged
qqeasonchen merged 1 commit into
apache:developfrom
qqeasonchen:docs/fold-reference-into-feature
Sep 10, 2026
Merged

docs: fold reference/ into feature/, split offset-lb-frame into three EN pages, rewrite redesign.md in English#5391
qqeasonchen merged 1 commit into
apache:developfrom
qqeasonchen:docs/fold-reference-into-feature

Conversation

@qqeasonchen

Copy link
Copy Markdown
Contributor

Follow-up to #5390 — folds the tree further per review feedback.

Motivation

Consolidate the docs layout: reference/ merges into feature/; the Chinese offset-lb-frame design page splits into three English feature pages; two architecture mechanism pages move to feature/; redesign.md becomes English.

Changes

reference/ → feature/ (7 pages)

client-java · http-api · admin-api · observability · deployment · protocols · storage-spi — all git mv'd with history.

architecture → feature (2 pages)

  • connector-api-split.md — the connector API split plan (a capability/mechanism page)
  • control-plane.md — delivery topology + state control plane + absorbed failure matrix

offset-lb-frame.md (中文, 391 lines) → three English feature pages

New page Covers
feature/offset-management.md The two offset layers (pull vs deliver/ack), per-backend mechanics table, the RocketMQ 5.x deferred-ACK chain (empopck), monotonic CAS-max writes, takeover behavior, retired designs
feature/load-balancing.md Full-stickiness model (no forwarding), self-reported instance load (LoadMeter), the /session/recommend scoring loop, session-granularity pinning, accepted trade-offs
feature/frame-protocol.md EventMeshFrame wire format (14B header + KV + data), msgType field mapping, FrameAdaptor SPI, WireCodec SPI, complete ingress/egress conversion chains for CloudEvents / MeshMessage / A2A, storage SPI frame handling

redesign.md → English

The 5,248-line Chinese design record is rewritten as a focused English design record: executive summary, the six iron rules (+ status snapshot), target architecture diagram, storage/SDK/ingress/egress/connector redesign summaries, the v1.2 decision log (15.1–15.8), the at-least-once vs exactly-once layer boundary, request-reply semantics, and the streaming modes — with cross-links into the current feature pages and a note that the historical appendices' live content now lives in the feature tree.

Result

docs/
├── index.md + introduction.md
├── quickstart/    getting-started · configuration
├── feature/       19 pages (core features · internals/mechanisms · API & ops reference)
└── architecture/  overview · security · redesign · review/{evidence, production-ha-plan}

Verification

  • All 199 internal .md links validated resolving (0 broken) across docs/** + README.
  • README documentation section updated to the new paths; index.md map rebuilt with Core features / Internals & mechanisms / API & operations groupings.

… EN pages, rewrite redesign.md in English

Follow-up to apache#5390 folding the tree further per review:

- reference/ (7 pages) merged into feature/: client-java, http-api,
  admin-api, observability, deployment, protocols, storage-spi
- architecture/connector-api-split.md and architecture/control-plane.md
  moved to feature/ (capability/mechanism pages)
- architecture/offset-lb-frame.md (Chinese) split into three English
  feature pages: offset-management.md (two offset layers, deferred ACK,
  monotonic writes, takeover), load-balancing.md (full-stickiness model,
  self-reported load, recommend loop), frame-protocol.md (EventMeshFrame
  wire format, FrameAdaptor/WireCodec SPIs, per-protocol chains)
- architecture/redesign.md rewritten in English as a design record
  (executive summary, iron rules, target architecture, decision log
  15.1-15.8, at-least-once vs exactly-once boundary, request-reply,
  streaming; historical appendices folded into current docs)

docs/ is now: quickstart/ + feature/ + architecture/ (overview, security,
redesign, review/) + index/introduction. All 199 internal .md links
validated resolving.
@qqeasonchen
qqeasonchen merged commit fd1ed35 into apache:develop Sep 10, 2026
1 check passed
qqeasonchen added a commit that referenced this pull request Sep 10, 2026
)

Follow-up to #5390/#5391 sweeping every place outside docs/ that still
referenced the old flat doc names:

- README.zh-CN.md: capability table + doc nav rewritten to the new
  quickstart/feature/architecture layout (mirrors the EN README map)
- CONTRIBUTING.md: arch-guard and storage-SPI matrix links
- docker/Dockerfile: deployment-mode note -> docs/feature/deployment.md
- eventmesh.properties (+dist copy): Connector Runtime section comment ->
  docs/feature/deployment.md
- DistributionMode javadoc -> docs/architecture/redesign.md
- sdk-java build.gradle OMA comment -> docs/feature/protocols.md
- sdk legacy-README.md links
- docs/**: link display text and prose mentions still naming old files
  (evidence.md, production-ha-plan.md, overview.md, client-java.md,
  protocols.md, control-plane.md, a2a-readiness.md, architecture-guard.md)

Repo-wide scan now finds zero stale references (the only remaining
docs/reference/ strings are opentelemetry.io spec URLs, untouched).
All 227 internal .md links across docs/ + READMEs + CONTRIBUTING resolve.
Touched modules compile and pass checkstyleMain.
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