imbajin commented on code in PR #511: URL: https://github.com/apache/hugegraph-doc/pull/511#discussion_r4191820524
########## content/en/docs/guides/shared-foundation-migration.md: ########## @@ -0,0 +1,220 @@ +--- +title: "1.8.0 shared-foundation migration" +linkTitle: "1.8.0 Java and upgrade migration" +description: "Update Java imports and plugins, then prepare matching Server, PD and Store upgrades for the 1.8.0 shared-foundation changes." +weight: 8 +--- + +The planned 1.8.0 migration changes Java imports and extension signatures, and requires Server, PD and Store to upgrade together. +Use this guide to identify affected code, rebuild your integrations and check existing data before deployment. + +## Find the work that applies to you + +| Your integration | What to prepare | +|---|---| +| Java code using Server IDs, schema metadata, queries or indexes | Update imports and affected signatures, then recompile against matching 1.8.0 artifacts. | +| Custom serializers, `HugeGraph` implementations or element subclasses | Adapt the SPI contracts and shared element state below. | +| Custom Gremlin imports or scripts | Replace the old `IdGenerator` class name and test packaged Gremlin startup. | +| Hubble, Java client or Computer integration | Apply the downstream exception changes when matching artifacts are available. | +| HStore deployment | Align the PD namespace, inspect legacy rebuilt indexes and upgrade all writers together. | +| Loader or another REST-only caller | Keep the independent client DTOs; migrate any actual affected Java calls. | + +These changes are planned for 1.8.0 and have not been released. +The [implementation PR](https://github.com/apache/hugegraph/pull/3270) includes the source migration document and compatibility fixtures. + +## Where shared code now lives + +Server core and struct previously carried separate implementations of several IDs, schema types, queries, elements and codecs. +The migration gives these shared types one owner so Server and Store can use the same implementation. +`hugegraph-core` continues to run the graph engine, `hugegraph-struct` supplies shared models and codecs, and `hugegraph-common` supplies utilities. + + + +*Core retains graph execution and adapters, Store retains storage and schema lifecycle, and struct/common own the shared implementations. +The arrows show shared ownership, not the full dependency tree.* + +| Owner | Responsibilities | +|---|---| +| struct | IDs, schema metadata, type codes, queries, base elements, property/byte codecs, index construction and analyzers | +| core | Transactions, traversal, tasks, schema mutation, backend adapters and index update orchestration | +| Store | PD-backed schema access, listeners and cache lifecycle through `SchemaGraph`/`SchemaDriver` | +| common | JWT signing/verification, shared auth constants and RPC configuration interfaces | + +The Server HStore adapter still needs PD and Store clients. Store retains its network, PD client and storage libraries. +PD and Store must not depend on core, and struct must not depend on core or PD clients. + +Core and Store implement `HugeGraphSupplier` to provide schema, configuration and clock access. +Shared base elements hold state and adjacency. `HugeVertex` and `HugeEdge` retain engine behavior and wrapper identity over that same state; +property mutation, cloning, removal, expiration and loading state must propagate through it. +Core serializers retain backend adapters and delegate shared encoding. +Shared index and OLAP selection receive schema candidates and result sinks from their callers; core keeps transaction writes and backend capability checks. + +## Update Java source and SPI implementations + +Start with the types your code imports. This ID construction call keeps the same string value while its imports move. + +**Before, using the 1.7.0 core API** + +```java +import org.apache.hugegraph.backend.id.Id; +import org.apache.hugegraph.backend.id.IdGenerator; + +Id vertexId = IdGenerator.of("vertex-1"); +``` + +**After, using the shared API** + +```java +import org.apache.hugegraph.id.Id; +import org.apache.hugegraph.id.IdGenerator; + +Id vertexId = IdGenerator.of("vertex-1"); +``` + +Recompile the application and its plugins after adapting source. Relocated types also change method descriptors, +so editing imports cannot make an old compiled jar binary-compatible. Removed core classes have no general compatibility package. +The [plugin examples](/docs/guides/custom-plugin/) still describe 1.7.0; apply the following mappings when targeting the migrated API. + +| Previous Java entry | Use in the migrated API | +|---|---| +| `org.apache.hugegraph.backend.id.*` | `org.apache.hugegraph.id.*` | +| `org.apache.hugegraph.schema.*` metadata | `org.apache.hugegraph.struct.schema.*` | +| `org.apache.hugegraph.backend.query.*` | `org.apache.hugegraph.query.*` | +| `org.apache.hugegraph.backend.store.Shard` | `org.apache.hugegraph.backend.Shard` | +| `org.apache.hugegraph.backend.store.BackendEntry.BackendColumn` | `org.apache.hugegraph.backend.BackendColumn` | +| `org.apache.hugegraph.structure.HugeIndex` | `org.apache.hugegraph.structure.Index` | +| Shared byte/encoding code in backend serializers | `org.apache.hugegraph.serializer.*` | +| Core `HugeException` | `org.apache.hugegraph.exception.HugeException` | +| `org.apache.hugegraph.SchemaGraph`/`SchemaDriver` | `org.apache.hugegraph.store.schema.*` | + +Schema mutation builders and backend-specific serializers remain in core, so apply these mappings only to affected types. +Client REST DTOs remain independent, including Toolchain's `org.apache.hugegraph.structure.graph.Shard`. + +| Extension point | Change in your implementation | +|---|---| +| `HugeGraph.sameAs(HugeGraph)` | Override `sameAs(org.apache.hugegraph.HugeGraphSupplier)`. There is no old-signature overload. | +| `GraphSerializer.writeIndex`/`readIndex` | Accept/return shared `org.apache.hugegraph.structure.Index`; update callers too. | +| Custom `HugeElement` subclass | Expose shared `BaseElement` through `element()` and adapt properties through `wrapProperty`. | + +Keep element adapters on the shared state; do not restore removed engine state fields or add a second adjacency collection. +For Gremlin `classImports` and scripts, replace `org.apache.hugegraph.backend.id.IdGenerator` with `org.apache.hugegraph.id.IdGenerator`. +Configuration-only class names need a packaged Gremlin startup check; Java compilation does not exercise them. + +The RPC interfaces `org.apache.hugegraph.rpc.RpcServiceConfig4Client` and `RpcServiceConfig4Server` now have one owner in common. +Their names and signatures stay the same, so this move requires no RPC import or configuration change. +`org.apache.hugegraph.auth.TokenGenerator` also belongs to common. Callers supply the signing secret and map JWT failures to their service responses. +Common's JWT dependencies are optional; direct JWT consumers must declare their required libraries. + +### Adapt downstream exceptions when matching artifacts are available + +| Previous downstream entry | Replacement | +|---|---| +| Hubble `org.apache.hugegraph.exception.HugeException` | `org.apache.hugegraph.exception.HubbleException` | +| Java client `org.apache.hugegraph.exception.NotSupportException` | `org.apache.hugegraph.exception.ClientNotSupportException` | +| Hubble's copy of `org.apache.hugegraph.license.MachineInfo` | Keep the import and use the common implementation. | + +Update constructors and catch clauses along with imports. `HubbleException` keeps its `RuntimeException` parent and string constructor. +`ClientNotSupportException` keeps its `ClientException` parent and message/cause and message/arguments constructors. +Computer's `HgkvDirImpl` is one affected client-exception caller. Struct's similarly named exceptions have different contracts. +Loader's REST boundary and independent client DTOs do not need an overall conversion to struct. + +The Toolchain and Computer changes are still unpublished downstream handoffs. They need matching publication, builds and packaged-classpath checks. +Inspect the built jars as well as the source tree for stale or transitive copies of the same class. + +## Prepare a coordinated service upgrade + +Upgrade Server, PD and Store together to matching release artifacts. This migration does not support mixed-version rolling upgrades. +The sequence below applies once those matching artifacts are available. + + + +*Back up data/configuration and check affected indexes, update imports/SPI and recompile, then upgrade matching services and align the PD namespace. +Verify packaged services and graph reads/writes. OLAP keys change from one row per vertex to one row per property and vertex; +matching legacy rows remain readable, overwritten values cannot be recovered, and mixed-version rolling upgrades are unsupported.* + +1. Back up graph data with the existing [backup and restore procedure](/docs/guides/backup-restore/) and preserve deployment configuration. +2. Prepare matching Server, PD and Store artifacts, plus rebuilt plugins and any required downstream integrations. +3. Align the metadata namespace using the settings below; preserve existing backend graph names. +4. Rehearse in a validation environment. Start the packaged services, read historical data and exercise affected queries and writes. +5. Pause writes for the coordinated deployment upgrade. Resume only after all Server and Store writers use matching artifacts and checks pass. + +The consolidation does not automatically rewrite graph data, rebuild indexes or recover historical entries. +Review the compatibility cases below during the rehearsal. + +### Match the PD metadata namespace + +Store's `pd.cluster` defaults to `hg`. Set it in Store `application.yml` as follows. + +```yaml +pd: + cluster: hg +``` + +The equivalent environment variable is `PD_CLUSTER`. + +| Server mode | Value that must match Store's `pd.cluster` | +|---|---| +| `usePD=true` | Server's `cluster` | +| `usePD=false` | The graph's `pd.cluster` | + +This namespace covers schema, graph configuration, cache watches and TTL-cleaner metadata. +One Store process cannot share a schema driver across conflicting namespaces. Review Comment: ⚠️ important. Blocking: yes. Summary: With usePD=false, the Server singleton MetaManager also binds the namespace process-wide: the first HStore graph connects it and a later conflicting pd.cluster is logged and ignored. Please require one namespace for all HStore graphs in a Server process and explain that later conflicts are ignored; sync the Chinese page. Evidence: [StandardHugeGraph binds and rejects a conflicting namespace at the paired Server head](https://github.com/apache/hugegraph/blob/40e10a7d7d0f9cb6e9a55f31f6848a469c04f465/hugegraph-server/hugegraph-core/src/main/java/org/apache/hugegraph/StandardHugeGraph.java#L253-L271). ########## content/en/docs/contribution-guidelines/contribute.md: ########## @@ -74,9 +76,19 @@ GitHub requires a username and token for Git authentication instead of a usernam When adding a third-party dependency, also update the license information included in the distribution: -1. Add the dependency's license file to `hugegraph-server/hugegraph-dist/release-docs/licenses/`. -2. Update `hugegraph-server/hugegraph-dist/release-docs/LICENSE`. If the dependency includes a NOTICE file, update `NOTICE` as well. -3. Run `hugegraph-server/hugegraph-dist/scripts/dependency/regenerate_known_dependencies.sh` to update the known-dependency list. +1. Add the dependency's license file to `install-dist/release-docs/licenses/`. +2. Update `install-dist/release-docs/LICENSE`. If the dependency includes a NOTICE file, update `NOTICE` as well. +3. From the repository root, prepare the current revision's Server, PD and Store distribution libraries before regenerating the inventory: + + ```bash + mvn install -DskipTests -Dmaven.javadoc.skip=true Review Comment: ⚠️ important. Blocking: no. Summary: This build omits clean, but the inventory collector scans jars in the versioned Server/PD/Store distribution directories; after removing a dependency in a reused checkout, leftover jars can keep it in the strict inventory and hide the removal. Please use mvn clean install -DskipTests -Dmaven.javadoc.skip=true or clear those distribution directories before collection, and sync Chinese. Evidence: [The collector recursively scans packaged lib/ext/plugins jars](https://github.com/apache/hugegraph/blob/40e10a7d7d0f9cb6e9a55f31f6848a469c04f465/install-dist/scripts/dependency/dependency_inventory.py#L83-L93); [the Server assembly is bound to package and writes a versioned output](https://github.com/apache/hugegraph/blob/40e10a7d7d0f9cb6e9a55f31f6848a469c04f465/hugegraph-server/hugegraph-dist/pom.xml#L156-L176); [PD assembly outputs are generated in package and cleaned by Maven clean](https://github.com/apache/hugegraph/blob/40e10a7d7d0f9cb6e9a55f3 1f6848a469c04f465/hugegraph-pd/hg-pd-dist/pom.xml#L47-L82); [Store uses the same package/clean output lifecycle](https://github.com/apache/hugegraph/blob/40e10a7d7d0f9cb6e9a55f31f6848a469c04f465/hugegraph-store/hg-store-dist/pom.xml#L47-L82). -- 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]
