qqeasonchen opened a new pull request, #5390:
URL: https://github.com/apache/eventmesh/pull/5390
## Motivation
The `docs/` tree had grown into 18 flat files with inconsistent names
(`eventmesh-*.md`, mixed EN/中文, internal design docs next to user guides) and
several stale claims vs. the code. This PR reorganizes everything into an
audience-oriented structure that renders cleanly to the website, fixes the
accuracy drift, and splits the 469-line features page into per-capability pages.
## New layout
```
docs/
├── index.md documentation map (entry point)
├── introduction.md what EventMesh is, the three planes, deployment shape
├── quickstart/ getting-started, configuration
├── feature/ one page per capability:
│ pubsub · delivery-reliability · streaming · lite-topic · a2a
│ (+a2a-readiness) · architecture-guard
├── reference/ client-java · http-api · admin-api ·
│ observability · deployment · protocols · storage-spi
└── architecture/ overview · control-plane (+state-store failure matrix
absorbed) · security (new) · redesign · offset-lb-frame ·
connector-api-split · review/ (evidence, production-ha-plan)
```
## Consolidations
| Old | New home |
| --- | --- |
| `eventmesh-features.md` (469 lines) | split into `feature/pubsub.md`,
`feature/delivery-reliability.md`, `feature/streaming.md`,
`feature/lite-topic.md`, `feature/a2a.md`; module map → `introduction.md` |
| `production-readiness.md` | checklist/runbook → `reference/deployment.md`;
metrics/SLO/alerts → `reference/observability.md` |
| `state-store-failure-matrix.md` | absorbed into
`architecture/control-plane.md` (§ State store failure matrix) |
| `eventmesh-*.md` naming | normalized to lowercase hyphenated slugs |
| `contrib/`, `architecture-review/` | folded into the tree
(`architecture/connector-api-split.md`, `architecture/review/`) |
## Accuracy fixes (verified against code)
- **Storage backends**: shipping plugins are rocketmq / rocketmq5 / kafka —
old docs listed pulsar/rabbitmq/redis/rocksdb storage modules that don't exist.
- **Meta store**: Nacos (+ in-memory single-instance); Consul/ETCD/ZK marked
as SPI work, not shipping.
- **Admin plane**: documented the fail-closed bearer guard (no token → `503
admin_locked`; only `/admin/health` exempt) from `UniAdminServer#guarded`.
- **Endpoints**: HTTP API page built from the actual `createContext`
registrations in `UniHttpServer`/`UniAdminServer` (incl. `/metrics` Prometheus
exposition and its 8 metric names from `prometheusMetrics`).
- **Recovery semantics** (#5379 re-dispatch), **connector generation
fencing** (#5382), **deployment modes** (#5380) documented from landed code.
- Note: the legacy `docs/eventmesh-features.md` section 5 "Configuration
highlights" quoted keys that are not read by the runtime
(`eventmesh.runtime.http.port` etc.) — the new configuration/feature pages only
cite keys that `EventMeshApplication` / `eventmesh.properties` actually read.
## Conventions introduced
- Per-page **Audience** banner (who it's for, what it covers) after the H1.
- Capability maturity always defers to the README capability-status table.
- Every page standalone-renderable for HTML website conversion; all **186
internal `.md` links validated resolving** (0 broken).
- README "Documentation" section rewritten around the new map.
## Verification
- Link validation script over `docs/**` + README: `checked 186 links;
broken: 0`.
- Renames done via `git mv` where tracked, so history follows.
- Markdown lint-by-eye: consistent heading levels, tables, code fences.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
