Skip to content

docs: explain shared foundation migration - #511

Open
imbajin wants to merge 2 commits into
apache:masterfrom
hugegraph:feat/struct-consolidation-1.8
Open

imbajin wants to merge 2 commits into
apache:masterfrom
hugegraph:feat/struct-consolidation-1.8

Conversation

@imbajin

@imbajin imbajin commented Oct 4, 2026 •

Copy link
Copy Markdown
Member

Java plugin documentation still uses the 1.7.0 API. Add English and Chinese guidance for the planned 1.8.0 shared-foundation migration so developers can quickly find which imports, extension contracts and deployment steps affect them.

The guide starts with a reader-impact table and explains module ownership through a before/after illustration. A small IdGenerator example shows the import change; API/SPI tables cover custom implementations. A second illustration and a step-by-step upgrade section explain coordinated Server/PD/Store upgrades, matching metadata namespaces and the OLAP key change.

Core and Struct duplicates become one shared implementation used by Core and Store.

Compatibility details remain explicit: affected long-text indexes may need rebuilding, matching legacy OLAP rows remain readable, overwritten values cannot be recovered, and mixed-version rolling upgrades are unsupported. Plugin and contributor pages link the new guide. Dependency-inventory instructions prepare matching packaged libraries before collection. Historical-version routing does not advertise an unavailable migration page.

Paired with apache/hugegraph#3270. Coordinate both merges after CI and review pass; downstream publication remains a release prerequisite.

Validation: source and link checks, strict Hugo build, fresh latest artifact validation, search-ranking regression checks, and English/Chinese desktop/mobile page checks including image loading and table overflow.

- document bilingual ownership and Java/SPI changes
- describe coordinated upgrades and legacy data limits
- align dependency inventory prerequisites and links
- Lead both languages with affected integrations and Java examples
- Explain ownership and upgrade steps with generated illustrations
- Keep compatibility limits in readable reference tables

@bitflicker64 bitflicker64 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


| Previous Java entry | Use in the migrated API |
|---|---|
| `org.apache.hugegraph.backend.id.*` | `org.apache.hugegraph.id.*` |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important: The backend.id.* row (line 80) and the backend.query.* row (line 82) tell readers to move every class in those packages, but some of them stay in core under their old names. At apache/hugegraph#3270 head eee539d49d67, hugegraph-core/.../backend/id/ still holds SnowflakeIdGenerator, and hugegraph-core/.../backend/query/ still holds QueryResults, ConditionQueryFlatten, EdgesQueryIterator, QueryBatch and QueryResultContext. Neither org.apache.hugegraph.id nor org.apache.hugegraph.query in struct has any of these classes, and 34 source files in that PR still import backend.query.QueryResults or SnowflakeIdGenerator from core. A plugin or custom backend that rewrites these imports as the table says will not compile, and QueryResults is a common import for custom backends. The note on line 90 only names schema builders and backend serializers as exceptions. Please list the moved classes explicitly in these two rows (Id, IdGenerator, EdgeId, IdUtil, SplicingIdGenerator; Query, ConditionQuery, Condition, IdQuery, IdPrefixQuery, IdRangeQuery, BatchConditionQuery, Aggregate), or say which classes stay in core. The same rows are on lines 79 and 81 of content/cn/docs/guides/shared-foundation-migration.md, and in docs/shared-foundation-migration.md of #3270.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants