GitHub user TongyiDai added a comment to the discussion: Architecture diagrams: how much detail and how to keep current?
I would make **A + an editable C-style source** the repository default. - Publish one high-level diagram that can be understood without toggling layers. - Keep the editable source in the repository; layers may hold optional detail when the component set overlaps cleanly. - Keep an ER diagram when the subsystem owns a meaningful persistence model. - Add a persistent per-flow diagram only when sequence/protocol detail is needed repeatedly. Otherwise, put that temporary detail in the issue/PR where the design is being discussed. That avoids making every subsystem pay the maintenance cost of B while preserving detail where it has durable value. The update rule should be based on architecture impact, not on whether somebody remembered to inspect the docs. A PR must update the relevant diagram when it changes any of: 1. a component or trust/deployment boundary; 2. a persisted entity or important relationship; 3. an external protocol/interface; 4. a critical cross-component call sequence represented by a retained flow diagram. Ownership should follow code ownership: the subsystem reviewer is responsible for rejecting a PR with stale architecture docs, while the PR author supplies the update. Store source and exported image together, and add a small CI check that the exported artifact was regenerated when the source changes. CI cannot prove semantic correctness, but it can prevent source/render drift. For audiences: - **Repository docs:** the canonical high-level export, ER diagram if relevant, and links to selected durable flow diagrams. - **Blog:** reuse the canonical diagram or a simplified export from the same source. - **Social:** a simplified derivative; never the source of truth. - **Issue/PR/internal working record:** temporary detailed flows are fine and need not become permanent architecture documentation. This gives a concrete policy: A is the required human-readable artifact, C is an implementation technique for its source, and B is an exception justified by a recurring reader question—not the default. GitHub link: https://github.com/apache/texera/discussions/8609#discussioncomment-18522681 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected]
