docs: regenerate product documentation set (getting started + configuration reference) - #5327
Closed
qqeasonchen wants to merge 7 commits into
Closed
docs: regenerate product documentation set (getting started + configuration reference)#5327qqeasonchen wants to merge 7 commits into
qqeasonchen wants to merge 7 commits into
Conversation
Add a canonical capability status table to the main README (EN + zh-CN) and
point every module doc at it, so maturity levels, recommendations and
migration targets live in exactly one place.
README.md / README.zh-CN.md — new 'Capability status' section:
HTTP + CloudEvents GA target recommended primary path
Kafka / RocketMQ storage GA target recommended, TCK-covered
SSE / WebSocket push Beta usable, semantics converging
Connector Runtime Beta usable, SPI migration ahead
A2A / Agent Gateway Experimental evaluate, D2 items pending
TCP/gRPC/OpenMessaging Legacy-compat existing users only
Status levels are defined in the table (GA / Beta / Experimental /
Legacy-compatible) so each term means one thing across all docs.
docs/a2a-protocol/README.md — EXPERIMENTAL banner now links the table as
the canonical maturity level.
docs/eventmesh-cloudevents-client-guide.md — legacy SDK note links the
table (HTTP+CE = GA, TCP/gRPC = legacy).
docs/production-readiness.md — production-readiness scope note points at
the table before its module/verification detail.
docs/eventmesh-uni-architecture-redesign.md,
docs/eventmesh-offset-lb-frame-design.md — marked as historical design
records; current status lives in the table.
Pure documentation change: 7 files, insertions only, no code touched.
Closes apache#5306.
Build the user-facing documentation set on top of the apache#5306 status table, generated from the current develop implementation: NEW docs/eventmesh-getting-started.md Zero-to-running guide: prerequisites, backend choice (rocketmq / rocketmq5 / kafka), Docker + source launch, health check, first publish, subscribe with distribution modes (LOAD_BALANCE / BROADCAST / MULTICAST), first SDK snippet, next-steps map. All examples match the live /events/* endpoints. NEW docs/eventmesh-configuration.md Complete configuration reference extracted from eventmesh-runtime/conf/eventmesh.properties + the runtime code: storage selection & per-backend keys (incl. rocketmq5 lite checkpoint interval, kafka SASL/SSL pass-through), ports/paths, security section (TLS/mTLS + the apache#5304 SecurityGate: filter chain, QuotaManager, AuditSink, 401/403/429 mapping), per-topic rate limiting, full admin (8081) and traffic (8080) endpoint tables, deployment checklist. README.md — 'Documentation' nav (getting started / configuration / client guide / production readiness); fix stale README_EN.md A2A link. README.zh-CN.md — 文档导航 section (equivalent). docs/eventmesh-cloudevents-client-guide.md — cross-link the two new docs at the top (kept as the full Chinese SDK reference). All internal markdown links validated (38 links, 0 broken after the README_EN fix). Content-only change: 2 new docs, 3 files touched.
The A2A guide was the only file in its own subdirectory; flatten it to a
top-level docs file to match the rest of the documentation set.
docs/a2a-protocol/README.md -> docs/a2a-protocol.md (content unchanged
except the capability-status link depth ../../README.md -> ../README.md)
References updated (6 links):
README.md (2) - feature bullet + status table
README.zh-CN.md (2) - same in Chinese
docs/eventmesh-configuration.md (1) - endpoint table
docs/eventmesh-getting-started.md (1) - next-steps
Verified: all 45 internal markdown links resolve; no 'a2a-protocol/' path
remains anywhere in the repo docs. (One pre-existing broken link in
eventmesh-uni-architecture-redesign.md to '-masa-migration-inventory.md'
predates this change and is untouched.)
Adds two new product docs (follow-up to the product-docs regeneration in apache#5327), updated against the post-apache#5296 architecture review state: - docs/eventmesh-architecture.md (NEW) Top-level system view across the control / data / agent planes. Covers the storage SPI contract (MeshStoragePlugin + TCK + TCK), the unified security gate (apache#5304, with the three wiring points: UniHttpServer / A2AGatewayHttpHandler / ConnectorScheduler), the A2A protocol stack (gateway service, topic factory, runtime bridge, agent cards, request lifecycle), the connector plane (24+ plugins, lifecycle, admin server), the architecture-guard module (apache#5305), and cross-cutting observability / configuration / build concerns. - docs/eventmesh-features.md (NEW) Feature-by-feature guide aligned to user intent: publish/subscribe, multiple subscriber transports, reliable delivery (at-least-once, retries, dead-letter), unified state control plane (apache#5301), unified security gate (apache#5304), A2A protocol, pluggable storage backends, connector ecosystem, pluggable meta service, filtering/transformation/ schema, serverless workflow, observability & operations, architecture-guard (apache#5305), legacy protocol compatibility, and i18n. Includes a feature-to-module map. - README.md / README.zh-CN.md Documentation nav now lists the two new docs alongside the existing getting-started / configuration / client-guide / production-readiness entries. The capability status table in the README remains the single source of truth for GA/Beta/Experimental/Legacy tags. All cross-references between the new docs and the existing docs/* set are validated (78 internal links, 0 broken in the new content).
…t-guide.md The old name was tied to a single protocol (CloudEvents). The new guide covers both the CloudEventsClient surface and the A2AClient surface, and consolidates all client-side guidance into one place — so the broader name is more accurate. What changed ------------ * docs/eventmesh-cloudevents-client-guide.md (425 lines) DELETED * docs/eventmesh-client-guide.md (685 lines) NEW The new guide is a full rewrite aligned to the post-apache#5296 architecture review state. It keeps every API covered in the old guide (CloudEventsClient pub/sub, request-reply, SSE/WS, Lite Topic for RocketMQ 5.x, Mode 1/Mode 2 streaming for LLM workloads, the RocketMQ 4.x / 5.x / Kafka backend matrix) and adds: * A separate A2AClient chapter (§11) covering builder config, sendTask / sendTaskSync / sendTaskAsync / getTaskStatus / cancelTask / streamTaskStatus / listAgents / registerAgentCard, the taskEpoch idempotency contract, and the /a2a/* endpoint surface. This was previously only mentioned in passing. * A security chapter (§9) that points at the unified SecurityGate (apache#5304) — three wiring points (UniHttpServer / A2AGatewayHttpHandler / ConnectorScheduler), QuotaManager / AuditSink, the Operation enum, the per-Resource quota keys, and what the client must do (attach Authorization header, emtenantid extension). * A reliability chapter (§10) mapping the storage-state taxonomy (L1 / L2 / L3) and DeliveryStateStore / SubscriptionStore / TaskStore to the client-visible ACK / retry / dead-letter / idempotency responsibilities. * A consolidated §12 backend-selection matrix (RocketMQ 4.x / 5.x / Kafka) with the client-visible behavioral differences, including the POP-vs-PULL delivery distinction and the SASL pass-through keys for Kafka. * An operational checklist (§14) mapping common client-side symptoms to the right Runtime / admin surface. * A §15 legacy-compat table mapping the deprecated EventMeshHttpClient / EventMeshTCPClient APIs to the new CloudEventsClient equivalents. * A new §16 code-locations table that points at every file referenced in the guide (CloudEventsClient, A2AClient, A2ATopicFactory, UniHttpServer, A2AGatewayHttpHandler, StreamingAgent, the three storage plugins, the security gate package, the architecture-guard module). Internal reference updates -------------------------- 6 files updated to point at the new file name: README.md (5 refs) README.zh-CN.md (5 refs) docs/eventmesh-architecture.md (2 refs) docs/eventmesh-configuration.md (1 ref) docs/eventmesh-features.md (4 refs) docs/eventmesh-getting-started.md (4 refs) No remaining 'eventmesh-cloudevents-client-guide' path anywhere in the repo docs. Verified by grep and by the 95-internal-link check (0 broken after the rename; the 1 pre-existing broken link in eventmesh-uni-architecture-redesign.md to '-masa-migration-inventory.md' predates this change and is untouched).
Aligns the file name with the other top-level product docs
(eventmesh-architecture.md, eventmesh-features.md, eventmesh-client-guide.md,
eventmesh-configuration.md, eventmesh-getting-started.md).
Pure rename — no content change.
docs/a2a-protocol.md -> docs/eventmesh-a2a-protocol.md
(git detected as a 100% similarity rename, 0 byte delta)
Internal references updated in 7 files (20 occurrences total):
README.md (2)
README.zh-CN.md (2)
docs/eventmesh-architecture.md (4 — was 2, plus 2 in the
Documentation table)
docs/eventmesh-client-guide.md (7 — added during the previous
client-guide rewrite; was 4)
docs/eventmesh-configuration.md (1)
docs/eventmesh-features.md (3 — was 2, plus 1 in the
Documentation table)
docs/eventmesh-getting-started.md (1)
No remaining 'a2a-protocol.md' path anywhere in the repo docs.
95 internal links checked, 0 broken after the rename (the 1
pre-existing broken link in eventmesh-uni-architecture-redesign.md
to '-masa-migration-inventory.md' predates this change).
Per request — README should not surface production-readiness.md
anymore. The Capability status table and the Documentation nav
block both lose their references to that file.
README.md
- Capability status table: drop the [text](docs/production-readiness.md)
link from the Connector Runtime row; keep the row text so the
capability still appears in the table.
- Documentation nav: drop the 'Production readiness' bullet.
README.zh-CN.md
- Same two changes in Chinese.
- Bonus: split the previously-merged 'Getting started / Configuration'
line into two separate bullets so all 5 product docs each get
their own line, matching the English README's structure.
After this commit, no README variant links to production-readiness.md
(verified by grep). 91 internal links checked, 0 broken in the new
content. The docs/production-readiness.md file itself is unchanged
(it is referenced from other docs/production-readiness callouts) — only
the README surface stops linking it.
Contributor
Author
README surface: drop
|
Contributor
Author
qqeasonchen
added a commit
that referenced
this pull request
Sep 2, 2026
) * docs: sync documentation with implementation status (issue #5306) Add a canonical capability status table to the main README (EN + zh-CN) and point every module doc at it, so maturity levels, recommendations and migration targets live in exactly one place. README.md / README.zh-CN.md — new 'Capability status' section: HTTP + CloudEvents GA target recommended primary path Kafka / RocketMQ storage GA target recommended, TCK-covered SSE / WebSocket push Beta usable, semantics converging Connector Runtime Beta usable, SPI migration ahead A2A / Agent Gateway Experimental evaluate, D2 items pending TCP/gRPC/OpenMessaging Legacy-compat existing users only Status levels are defined in the table (GA / Beta / Experimental / Legacy-compatible) so each term means one thing across all docs. docs/a2a-protocol/README.md — EXPERIMENTAL banner now links the table as the canonical maturity level. docs/eventmesh-cloudevents-client-guide.md — legacy SDK note links the table (HTTP+CE = GA, TCP/gRPC = legacy). docs/production-readiness.md — production-readiness scope note points at the table before its module/verification detail. docs/eventmesh-uni-architecture-redesign.md, docs/eventmesh-offset-lb-frame-design.md — marked as historical design records; current status lives in the table. Pure documentation change: 7 files, insertions only, no code touched. Closes #5306. * docs: regenerate product documentation set (follow-up to #5306) Build the user-facing documentation set on top of the #5306 status table, generated from the current develop implementation: NEW docs/eventmesh-getting-started.md Zero-to-running guide: prerequisites, backend choice (rocketmq / rocketmq5 / kafka), Docker + source launch, health check, first publish, subscribe with distribution modes (LOAD_BALANCE / BROADCAST / MULTICAST), first SDK snippet, next-steps map. All examples match the live /events/* endpoints. NEW docs/eventmesh-configuration.md Complete configuration reference extracted from eventmesh-runtime/conf/eventmesh.properties + the runtime code: storage selection & per-backend keys (incl. rocketmq5 lite checkpoint interval, kafka SASL/SSL pass-through), ports/paths, security section (TLS/mTLS + the #5304 SecurityGate: filter chain, QuotaManager, AuditSink, 401/403/429 mapping), per-topic rate limiting, full admin (8081) and traffic (8080) endpoint tables, deployment checklist. README.md — 'Documentation' nav (getting started / configuration / client guide / production readiness); fix stale README_EN.md A2A link. README.zh-CN.md — 文档导航 section (equivalent). docs/eventmesh-cloudevents-client-guide.md — cross-link the two new docs at the top (kept as the full Chinese SDK reference). All internal markdown links validated (38 links, 0 broken after the README_EN fix). Content-only change: 2 new docs, 3 files touched. * docs: flatten docs/a2a-protocol/README.md to docs/a2a-protocol.md The A2A guide was the only file in its own subdirectory; flatten it to a top-level docs file to match the rest of the documentation set. docs/a2a-protocol/README.md -> docs/a2a-protocol.md (content unchanged except the capability-status link depth ../../README.md -> ../README.md) References updated (6 links): README.md (2) - feature bullet + status table README.zh-CN.md (2) - same in Chinese docs/eventmesh-configuration.md (1) - endpoint table docs/eventmesh-getting-started.md (1) - next-steps Verified: all 45 internal markdown links resolve; no 'a2a-protocol/' path remains anywhere in the repo docs. (One pre-existing broken link in eventmesh-uni-architecture-redesign.md to '-masa-migration-inventory.md' predates this change and is untouched.) * docs: add architecture and features product documentation Adds two new product docs (follow-up to the product-docs regeneration in #5327), updated against the post-#5296 architecture review state: - docs/eventmesh-architecture.md (NEW) Top-level system view across the control / data / agent planes. Covers the storage SPI contract (MeshStoragePlugin + TCK + TCK), the unified security gate (#5304, with the three wiring points: UniHttpServer / A2AGatewayHttpHandler / ConnectorScheduler), the A2A protocol stack (gateway service, topic factory, runtime bridge, agent cards, request lifecycle), the connector plane (24+ plugins, lifecycle, admin server), the architecture-guard module (#5305), and cross-cutting observability / configuration / build concerns. - docs/eventmesh-features.md (NEW) Feature-by-feature guide aligned to user intent: publish/subscribe, multiple subscriber transports, reliable delivery (at-least-once, retries, dead-letter), unified state control plane (#5301), unified security gate (#5304), A2A protocol, pluggable storage backends, connector ecosystem, pluggable meta service, filtering/transformation/ schema, serverless workflow, observability & operations, architecture-guard (#5305), legacy protocol compatibility, and i18n. Includes a feature-to-module map. - README.md / README.zh-CN.md Documentation nav now lists the two new docs alongside the existing getting-started / configuration / client-guide / production-readiness entries. The capability status table in the README remains the single source of truth for GA/Beta/Experimental/Legacy tags. All cross-references between the new docs and the existing docs/* set are validated (78 internal links, 0 broken in the new content). * docs: rename eventmesh-cloudevents-client-guide.md to eventmesh-client-guide.md The old name was tied to a single protocol (CloudEvents). The new guide covers both the CloudEventsClient surface and the A2AClient surface, and consolidates all client-side guidance into one place — so the broader name is more accurate. What changed ------------ * docs/eventmesh-cloudevents-client-guide.md (425 lines) DELETED * docs/eventmesh-client-guide.md (685 lines) NEW The new guide is a full rewrite aligned to the post-#5296 architecture review state. It keeps every API covered in the old guide (CloudEventsClient pub/sub, request-reply, SSE/WS, Lite Topic for RocketMQ 5.x, Mode 1/Mode 2 streaming for LLM workloads, the RocketMQ 4.x / 5.x / Kafka backend matrix) and adds: * A separate A2AClient chapter (§11) covering builder config, sendTask / sendTaskSync / sendTaskAsync / getTaskStatus / cancelTask / streamTaskStatus / listAgents / registerAgentCard, the taskEpoch idempotency contract, and the /a2a/* endpoint surface. This was previously only mentioned in passing. * A security chapter (§9) that points at the unified SecurityGate (#5304) — three wiring points (UniHttpServer / A2AGatewayHttpHandler / ConnectorScheduler), QuotaManager / AuditSink, the Operation enum, the per-Resource quota keys, and what the client must do (attach Authorization header, emtenantid extension). * A reliability chapter (§10) mapping the storage-state taxonomy (L1 / L2 / L3) and DeliveryStateStore / SubscriptionStore / TaskStore to the client-visible ACK / retry / dead-letter / idempotency responsibilities. * A consolidated §12 backend-selection matrix (RocketMQ 4.x / 5.x / Kafka) with the client-visible behavioral differences, including the POP-vs-PULL delivery distinction and the SASL pass-through keys for Kafka. * An operational checklist (§14) mapping common client-side symptoms to the right Runtime / admin surface. * A §15 legacy-compat table mapping the deprecated EventMeshHttpClient / EventMeshTCPClient APIs to the new CloudEventsClient equivalents. * A new §16 code-locations table that points at every file referenced in the guide (CloudEventsClient, A2AClient, A2ATopicFactory, UniHttpServer, A2AGatewayHttpHandler, StreamingAgent, the three storage plugins, the security gate package, the architecture-guard module). Internal reference updates -------------------------- 6 files updated to point at the new file name: README.md (5 refs) README.zh-CN.md (5 refs) docs/eventmesh-architecture.md (2 refs) docs/eventmesh-configuration.md (1 ref) docs/eventmesh-features.md (4 refs) docs/eventmesh-getting-started.md (4 refs) No remaining 'eventmesh-cloudevents-client-guide' path anywhere in the repo docs. Verified by grep and by the 95-internal-link check (0 broken after the rename; the 1 pre-existing broken link in eventmesh-uni-architecture-redesign.md to '-masa-migration-inventory.md' predates this change and is untouched). * docs: rename a2a-protocol.md to eventmesh-a2a-protocol.md Aligns the file name with the other top-level product docs (eventmesh-architecture.md, eventmesh-features.md, eventmesh-client-guide.md, eventmesh-configuration.md, eventmesh-getting-started.md). Pure rename — no content change. docs/a2a-protocol.md -> docs/eventmesh-a2a-protocol.md (git detected as a 100% similarity rename, 0 byte delta) Internal references updated in 7 files (20 occurrences total): README.md (2) README.zh-CN.md (2) docs/eventmesh-architecture.md (4 — was 2, plus 2 in the Documentation table) docs/eventmesh-client-guide.md (7 — added during the previous client-guide rewrite; was 4) docs/eventmesh-configuration.md (1) docs/eventmesh-features.md (3 — was 2, plus 1 in the Documentation table) docs/eventmesh-getting-started.md (1) No remaining 'a2a-protocol.md' path anywhere in the repo docs. 95 internal links checked, 0 broken after the rename (the 1 pre-existing broken link in eventmesh-uni-architecture-redesign.md to '-masa-migration-inventory.md' predates this change). * docs: drop production-readiness.md from README nav and capability table Per request — README should not surface production-readiness.md anymore. The Capability status table and the Documentation nav block both lose their references to that file. README.md - Capability status table: drop the [text](docs/production-readiness.md) link from the Connector Runtime row; keep the row text so the capability still appears in the table. - Documentation nav: drop the 'Production readiness' bullet. README.zh-CN.md - Same two changes in Chinese. - Bonus: split the previously-merged 'Getting started / Configuration' line into two separate bullets so all 5 product docs each get their own line, matching the English README's structure. After this commit, no README variant links to production-readiness.md (verified by grep). 91 internal links checked, 0 broken in the new content. The docs/production-readiness.md file itself is unchanged (it is referenced from other docs/production-readiness callouts) — only the README surface stops linking it. * docs: fold README Quick start into eventmesh-getting-started.md The README carried a 6-step Quick start (pull image, run, publish, subscribe, receive via 3 transports, unsubscribe) that overlapped heavily with docs/eventmesh-getting-started.md. To eliminate the duplication and keep the README surface concise, the entire Quick start section is now collapsed to a one-paragraph pointer that links to the getting-started guide. What changed ------------ * README.md (Quick start): 122 lines removed, replaced with a 6-line pointer to docs/eventmesh-getting-started.md. * README.zh-CN.md (\u5feb\u901f\u5165\u95e8): 220 lines removed, replaced with a 5-line Chinese pointer. * docs/eventmesh-getting-started.md: +20 lines \u2014 added an SSE and a WebSocket curl example to \u00a75 (the three-receive-transports section), so the getting-started guide is now strictly a superset of what the README Quick start used to show. The \u00a76 SDK / \u00a77 Where-to-go-next numbering was preserved (the new curl examples slot into \u00a75). Net effect: 312 lines removed across 3 files; the user-facing content (one-liner pointer + the curl examples) is now in exactly one place. Quality gate: 92 internal links checked, 0 broken in the new content.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Regenerates the product documentation set on top of the #5306 capability status table — a Getting Started guide and a complete Configuration Reference, both extracted from the current develop implementation (not from stale design notes), plus README navigation into the set.
Follow-up to #5326 (same area, keeps that PR reviewable on its own).
What's new
docs/eventmesh-getting-started.md(new)Zero-to-running in one page:
rocketmq/rocketmq5/kafkawith what each enables)./gradlew :eventmesh-runtime:dist)curl), subscribe + long-poll + ACK, distribution-mode table (LOAD_BALANCE / BROADCAST / MULTICAST)CloudEventsClientSDK snippetEvery example was written against the live endpoints (
/events/publish,/events/subscribe,/events/poll,/events/ack,/admin/health) as they exist on develop.docs/eventmesh-configuration.md(new)Every configuration key in one place, with precedence (
-D> env > properties file):eventmesh.storage.type/EVENTMESH_STORAGE_TYPE)eventmesh.rocketmq5.lite.checkpoint.interval.mscrash-replay semantics and the full Kafkasecurity.*/sasl.*/ssl.*pass-througheventmesh.http.port8080,eventmesh.admin.port8081,eventmesh.ws.port−1,eventmesh.offset.path)/admin/ratelimitUniAdminService/UniHttpServercreateContextregistrations, all 26+12 endpointsREADME.md / README.zh-CN.md
docs/a2a-protocol/README_EN.mdlink (onlyREADME.mdexists)docs/eventmesh-cloudevents-client-guide.mdVerification
git grep createContexton the actual server classeseventmesh-runtime/conf/eventmesh.propertiesand the-Doverrides in the boot pathRelationship to #5326 / #5306
#5326 established where status lives (the capability table). This PR fills in the product docs users read to actually run EventMesh. Merging order: either order works — this PR only links the table, it doesn't modify it.