docs: sync documentation with implementation status (issue #5306) - #5326
Merged
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
Consolidating #5327 into this PRThe companion PR #5327 ( Branch state after this push Commits, oldest first:
The PR body has been rewritten to reflect the consolidated scope. The #5327 has been closed as superseded. Why consolidate
No file content changed in this consolidation — only the branch |
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.
Contributor
Author
Follow-up: fold README Quick start into
|
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.
Apache EventMesh product documentation set (issue #5306 + follow-ups)
This PR is the single landing for the post-#5296 architecture review
documentation set. It started as the status-table sync for #5306, and
grew into the full product-docs regeneration as additional issues
landed on
develop. The earlier companion PR (#5327,docs/product-docs) was collapsed into this branch to keep reviewsurface to a single PR — its commits are now on top of the original
status-table commit.
What this PR contains
609090602d5dbdea57eventmesh-getting-started.md(zero-to-running),eventmesh-configuration.md(every runtime key, security & quota, full admin/traffic endpoint tables), README nav.1f8e491c7docs/a2a-protocol/README.mdtodocs/a2a-protocol.md(no more subdirectory).05b171271eventmesh-architecture.md(control / data / agent planes; storage SPI; security gate; A2A stack) +eventmesh-features.md(feature-by-feature guide, 15 sections).f3b7941c7eventmesh-cloudevents-client-guide.md→eventmesh-client-guide.md, and rewrite it to also cover theA2AClientsurface, the unified security gate, reliability taxonomy, backend-selection matrix, and a legacy-compat table.9dc832066a2a-protocol.md→eventmesh-a2a-protocol.md(aligns with the other top-level product docs).62da19f63production-readiness.mdfrom the README surface (table link + nav bullet); also split the merged "Getting started / Configuration" ZH nav line.Files (12 total)
Documentation set after this PR lands
docs/eventmesh-getting-started.mddocs/eventmesh-configuration.mddocs/eventmesh-client-guide.mdCloudEventsClient(pub/sub, request-reply, SSE/WS, RocketMQ 5.x Lite Topic, LLM streaming Mode 1/2) +A2AClient(task lifecycle,taskEpoch, agent card registry) + backend selection matrix + legacy-compat tabledocs/eventmesh-architecture.mdMeshStoragePlugin+ TCK), unified security gate (#5304, 3 wiring points), A2A protocol stack, connector plane, architecture-guard (#5305)docs/eventmesh-features.mddocs/eventmesh-a2a-protocol.mddocs/production-readiness.mddocs/eventmesh-uni-architecture-redesign.mddocs/eventmesh-offset-lb-frame-design.mdEventMeshFramedesign (single protocol path, #5299)Quality gates
eventmesh-uni-architecture-redesign.mdto-masa-migration-inventory.mdpredates this PR).grepconfirms no remaininga2a-protocol.md,eventmesh-cloudevents-client-guide.md, orproduction-readiness.mdpaths in the README.developsource tree.Closes