docs: explain shared foundation migration

[imbajin]

中文说明 (Chinese Summary)

背景与目标

在 HugeGraph 1.8.0 中，底层对 Core 和 Struct 重复代码进行了重构与下沉（Shared Foundation），合并为 Core 与 Store 共同依赖的统一基础模块。为解决旧文档插件 API 与包名停留在 1.7.0 的问题，本 PR 新增 1.8.0 基础模块迁移指南，并同步更新插件开发与贡献者构建指引。

主要改动

1. 新增共享基础模块迁移指南 (shared-foundation-migration.md):
   • 读者影响矩阵：梳理各模块改动对插件开发者、平台运维人员和核心贡献者的影响范围。
   • 包名与接口变更对照：以 IdGenerator 等核心类为例，清晰列出新旧 package import 对照表与 API/SPI 调整。
   • 集群协同升级：说明 Server、PD 与 Store 的版本一致性升级要求、元数据命名空间规范以及 OLAP 存储格式变更。
2. 插件开发与贡献指引同步 (custom-plugin.md, contribute.md):
   • 修正自定义插件示例中的引用包名与依赖声明。
   • 更新 Maven 3.10 构建环境下的依赖展平说明。
3. 架构示意图与路由维护 (version_routes.json, 图片静态资源):
   • 引入模块归属变更示意图，并在文档路由中进行规范注册。

边界与注意事项

• 兼容性说明：长文本索引可能需要重新构建；历史遗留的 OLAP 行数据保持可读；不支持跨版本节点的混合滚动升级。

---

English Description

Summary

Add a comprehensive bilingual guide for the 1.8.0 Shared-Foundation Migration (consolidating duplicated Core and Struct components into unified shared modules), and update plugin development and contributor build instructions.

Key Changes

1. Shared Foundation Migration Guide (shared-foundation-migration.md):
   • Reader impact matrix: clearly outlines which changes affect plugin developers, cluster operators, and core contributors.
   • Package & SPI mapping: provides explicit import mappings (e.g. IdGenerator) and API/SPI comparison tables for custom extensions.
   • Coordinated upgrades: documents coordinated Server/PD/Store upgrade requirements, metadata namespaces, and OLAP storage format compatibility.
2. Plugin & Contributor Docs (custom-plugin.md, contribute.md):
   • Updated custom plugin build templates and package paths.
   • Updated contributor build requirements, including Maven 3.10 POM flattening.
3. Diagrams & Navigation:
   • Added module architecture illustrations and registered version routing.

Scope & Boundaries

• Long-text indexes may require rebuilding after upgrading.
• Mixed-version rolling upgrades across cluster nodes are not supported.

---

Related Implementation PRs

• Server Foundation: apache/hugegraph#3270 (merged)
• Import Cleanup: apache/hugegraph#3307

Verification

• Hugo 0.165 Extended bilingual build passed
• Markdown links & anchors validated (dist/validate-links.sh)

Architectural Overview

[bitflicker64]

Blocking: yes. Summary: The guide's API and SPI claims match apache/hugegraph#3270, but its import table maps two whole packages to struct when some of their classes stay in core, so readers who apply those rows as written get imports that do not compile. Score 7/10. Evidence: static review of exact head 611003d against #3270 head eee539d49d67 (class locations via git ls-tree, HugeGraph.sameAs, GraphSerializer.writeIndex/readIndex, HugeElement.element()/wrapProperty, BaseVertex.TypeContext, pd.cluster default hg, Server cluster/usePD and graph pd.cluster options, regenerate_known_dependencies.sh and dependency_inventory.py); all latest-head checks pass.

[imbajin]

Blocking: yes. Summary: The migration guide omits the Server-wide PD namespace binding and the inventory command can retain stale jars on a reused checkout. Evidence: Paired implementation and inventory-collector locations are linked in the inline comments.

[imbajin]

Blocking: yes. Summary: The documented root Maven clean command can remove the PD and Store source trees through their distribution modules' broad Clean filesets. Evidence: the merged Server #3270 POMs point dist.dir at each parent module directory and configure it as a fileset; Maven Clean selects all paths when includes is empty, as linked in the inline comment.

[bitflicker64]

Blocking: no. Summary: The guide's class locations, SPI signatures, PD namespace rules and build prerequisites match merged apache/hugegraph#3270 (master 5039e5b67), and the earlier findings on the ID/query rows and the Server-wide namespace binding are fixed at this head. The root mvn clean install in the inventory step is safe: I ran mvn clean from the root of a throwaway master worktree, and it removed only the versioned distribution directories and tarballs and left every tracked file in place. One minor gap remains: the schema row doesn't say that SchemaManager stays in core. Evidence: read the full exact-head diff (EN and CN); used git ls-files on apache/hugegraph master to check every relocated and retained class in the mapping table; checked HugeGraph.sameAs(HugeGraphSupplier), GraphSerializer.writeIndex/readIndex(Index), HugeElement.element()/wrapProperty, BaseVertex.TypeContext, the Store @Value("${pd.cluster:hg}"), the StandardHugeGraph MetaManager binding and warning, the root POM (maven.compiler.release 17, requireMavenVersion [3.6.3,), flatten in process-resources) and the dependency_inventory.py distribution paths. mvn -o clean from the root, run with stale apache-hugegraph-{server,pd,store}-1.8.0/lib jars present, removed those directories and left git status empty: the effective PD/Store Clean filesets inherit the includes *.tar, *.tar.gz, .flattened-pom.xml and ${final.name}/** from the parent POMs. Latest-head prepare check passes.

[bitflicker64]

Blocking: no. Summary: At 13ecb59 the guide's class mappings (including the new backend.query.serializer row and the SchemaManager note), SPI signatures, PD namespace rules and build prerequisites match apache/hugegraph master 36bc1c64b, and the English and Chinese pages agree. One minor inaccuracy is new in this head: the sentence about which *.tar.gz files clean removes names the repository root, but the wildcard applies to the three module directories. Evidence: read the full exact-head diff (EN and CN) and the 2104942..13ecb59 delta; used git ls-tree on master 36bc1c64b and the 1.7.0 tag to check every moved and retained class in the mapping table, HugeGraph.sameAs(HugeGraphSupplier), GraphSerializer.writeIndex/readIndex with Index, HugeElement.element()/wrapProperty, BaseVertex.TypeContext, Store @Value("${pd.cluster:hg}"), the StandardHugeGraph namespace warning, optional jjwt in hugegraph-common, the root POM (maven.compiler.release 17, requireMavenVersion [3.6.3,), flatten in process-resources) and the install-dist paths; ran mvn -o clean from the root of a throwaway master worktree with marker archives and directories, which left git status clean for tracked files; link targets, images and version_routes.json entries exist at the head, git diff --check is clean and all latest-head checks pass.