Add root-level GLV examples and fix existing example issues

CHANGELOG.asciidoc

@@ -27,6 +27,8 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 * Added getter for `parameterItems` and `valueTraversal` on `DifferenceStep`.
 * Added properties to `Element` objects found in a `Path` for GraphSON v2 and v3 and GraphBinary.
 * Fixed edge properties for GraphBinary which were not deserializing properly.
+* Improved GLV examples reliability and documentation with step-by-step instructions.
+* Added root-level GLV examples in `glv-examples/` directory that use published driver versions for easy out-of-the-box usage, separate from module-level examples that use local development code.
 * Bump netty to 4.1.125.Final
 
 [[release-3-7-4]]

docs/src/dev/developer/development-environment.asciidoc

@@ -497,6 +497,11 @@ and GLVs will run automatically with integration tests against the TinkerTransac
 ** Generate web site locally: `bin/generate-home.sh`
 ** Publish web site: `bin/publish-home.sh <username>`
 
+[[glv-examples]]
+== GLV Examples
+
+TinkerPop maintains GLV examples in two distinct locations. User-facing examples in the `glv-examples/` directory utilize published driver versions and are referenced in the main documentation. Module-level examples within each GLV directory (e.g., `gremlin-python/src/main/python/examples/`) use local development code to ensure compatibility and prevent regressions.
+
 [[building-on-windows]]
 == Building On Windows
 

docs/src/dev/developer/release.asciidoc

@@ -329,6 +329,13 @@ the help of a PMC member for those steps.
 . Consider the changes made to Gremlin and determine if the community needs to organize a PR to [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/gremlin) to keep TypeScript up to date.
 . Ensure that the GLV examples compile and run with the latest image and dependencies: `bin/run-examples.sh`.
 .. Make changes as necessary to update the examples.
+. Update root-level GLV examples to use the new release version:
+.. Update version numbers in `glv-examples/gremlin-java/pom.xml` to reference the new release version
+.. Update version numbers in `glv-examples/gremlin-javascript/package.json` to reference the new release version  
+.. Update version numbers in `glv-examples/gremlin-python/requirements.txt` to reference the new release version
+.. Update version numbers in `glv-examples/gremlin-dotnet/*/\*.csproj` to reference the new release version
+.. Update version numbers in `glv-examples/gremlin-go/go.mod` to reference the new release version
+.. Test that all root-level examples work correctly with the new published versions
 . Generate a list of dead branches that will be automatically deleted and post them as a DISCUSS thread for review, then once consensus is reached removed those branches.
 . Set up the IO tests for the current `SNAPSHOT` as discussed in the <<io,IO Documentation and Testing Section>>
 

docs/src/reference/gremlin-variants.asciidoc

@@ -521,31 +521,48 @@ that can be used to fulfill the `gremlingo.Set` interface if desired.
 === Application Examples
 
 The TinkerPop source code contains some sample applications that demonstrate the basics of Gremlin-Go. They
-can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-go/examples/[here]
+can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/glv-examples/gremlin-go/[here]
 and are designed to connect to a running <<gremlin-server,Gremlin Server>> configured with the
 `conf/gremlin-server.yaml` and `conf/gremlin-server-modern.yaml` files as included with the standard release packaging.
 
-To run the examples, first download an image of Gremlin Server from Docker Hub:
+This guide assumes Gremlin Server will be executed using Docker. Alternatively, Gremlin Server can run locally (see the <<gremlin-server,Gremlin Server>> documentation for this option).
+
+To start Gremlin Server using Docker, first download an image of Gremlin Server from Docker Hub:
+
 [source,shell]
 ----
 docker pull tinkerpop/gremlin-server
 ----
 
-The remote connection and basic Gremlin examples can be run on a clean server, which uses the default configuration file
-`conf/gremlin-server.yaml`. To start a clean server, launch a new container with `docker run`:
+Clean server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server
 ----
 
-The traversal examples should be run on a server configured to start with the Modern toy graph, using `conf/gremlin-server-modern.yaml`.
-To start a server with the Modern graph preloaded, launch a new container with `docker run`:
+Modern toy graph server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server conf/gremlin-server-modern.yaml
 ----
 
-Each example can now be run with the following commands:
+The remote connection and basic Gremlin examples can be run on a clean server, while traversal examples should be 
+run on a server with the Modern graph preloaded.
+
+==== Prerequisites
+- Compatible Go installed (see <<development-environment,Development Environment>> for supported versions)
+
+Navigate to the examples directory:
+
+[source,shell]
+----
+cd glv-examples/gremlin-go
+----
+
+Run the examples:
+
 [source,shell]
 ----
 go run connections.go
@@ -1263,19 +1280,62 @@ execute it.
 === Application Examples
 
 The TinkerPop source code contains some sample applications that demonstrate the basics of Gremlin-Java. They
-can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-driver/src/main/java/examples/[here].
+can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/glv-examples/gremlin-java/[here]
+and are designed to connect to a running <<gremlin-server,Gremlin Server>> configured with the
+`conf/gremlin-server.yaml` and `conf/gremlin-server-modern.yaml` files as included with the standard release packaging.
+
+This guide assumes Gremlin Server will be executed using Docker. Alternatively, Gremlin Server can run locally (see the <<gremlin-server,Gremlin Server>> documentation for this option).
 
-The remote connection examples in particular are designed to connect to a running <<gremlin-server,Gremlin Server>>
-configured with the `conf/gremlin-server.yaml` file as included with the standard release packaging.
+To start Gremlin Server using Docker, first download an image of Gremlin Server from Docker Hub:
 
-To do so, download an image of Gremlin Server from Docker Hub, then launch a new container with `docker run`:
 [source,shell]
 ----
 docker pull tinkerpop/gremlin-server
+----
+
+Clean server:
+
+[source,shell]
+----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server
 ----
 
-All examples can then be run using your IDE of choice.
+Modern toy graph server:
+
+[source,shell]
+----
+docker run -d -p 8182:8182 tinkerpop/gremlin-server conf/gremlin-server-modern.yaml
+----
+
+The remote connection and basic Gremlin examples can be run on a clean server, while traversal examples should be 
+run on a server with the Modern graph preloaded.
+
+==== Prerequisites
+- Compatible JDK installed (see <<development-environment,Development Environment>> for supported versions)
+- Maven installed
+
+Navigate to the examples directory:
+
+[source,shell]
+----
+cd glv-examples/gremlin-java
+----
+
+Build the examples with Maven:
+
+[source,shell]
+----
+mvn clean install
+----
+
+Run the examples:
+
+[source,shell]
+----
+java -cp target/run-examples-shaded.jar examples.Connections
+java -cp target/run-examples-shaded.jar examples.BasicGremlin
+java -cp target/run-examples-shaded.jar examples.ModernTraversals
+----
 
 [[gremlin-javascript]]
 == Gremlin-JavaScript
@@ -1687,37 +1747,56 @@ no `Graph` instance to deserialize a result into on the client-side. A workaroun
 === Application Examples
 
 The TinkerPop source code contains some sample applications that demonstrate the basics of Gremlin-JavaScript. They
-can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-javascript/examples/[here]
+can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/glv-examples/gremlin-javascript/[here]
 and are designed to connect to a running <<gremlin-server,Gremlin Server>> configured with the
 `conf/gremlin-server.yaml` and `conf/gremlin-server-modern.yaml` files as included with the standard release packaging.
 
-To run the examples, first download an image of Gremlin Server from Docker Hub:
+This guide assumes Gremlin Server will be executed using Docker. Alternatively, Gremlin Server can run locally (see the <<gremlin-server,Gremlin Server>> documentation for this option).
+
+To start Gremlin Server using Docker, first download an image of Gremlin Server from Docker Hub:
+
 [source,shell]
 ----
 docker pull tinkerpop/gremlin-server
 ----
 
-The remote connection and basic Gremlin examples can be run on a clean server, which uses the default configuration file
-`conf/gremlin-server.yaml`. To start a clean server, launch a new container with `docker run`:
+Clean server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server
 ----
 
-The traversal examples should be run on a server configured to start with the Modern toy graph, using `conf/gremlin-server-modern.yaml`.
-To start a server with the Modern graph preloaded, launch a new container with `docker run`:
+Modern toy graph server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server conf/gremlin-server-modern.yaml
 ----
 
-Make sure to install all necessary packages:
+The remote connection and basic Gremlin examples can be run on a clean server, while traversal examples should be 
+run on a server with the Modern graph preloaded.
+
+==== Prerequisites
+- Compatible Node.js installed (see <<development-environment,Development Environment>> for supported versions)
+- npm installed
+
+Navigate to the examples directory:
+
+[source,shell]
+----
+cd glv-examples/gremlin-javascript
+----
+
+Install the dependencies:
+
 [source,shell]
 ----
 npm install
 ----
 
-Each example can now be run with the following commands:
+Run the examples:
+
 [source,shell]
 ----
 node connections.js
@@ -2088,34 +2167,60 @@ dotnet new gremlin -o MyFirstGremlinProject
 === Application Examples
 
 The TinkerPop source code contains some sample applications that demonstrate the basics of Gremlin-Dotnet. They
-can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-dotnet/Examples/[here]
+can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/glv-examples/gremlin-dotnet/[here]
 and are designed to connect to a running <<gremlin-server,Gremlin Server>> configured with the
 `conf/gremlin-server.yaml` and `conf/gremlin-server-modern.yaml` files as included with the standard release packaging.
 
-To run the examples, first download an image of Gremlin Server from Docker Hub:
+This guide assumes Gremlin Server will be executed using Docker. Alternatively, Gremlin Server can run locally (see the <<gremlin-server,Gremlin Server>> documentation for this option).
+
+To start Gremlin Server using Docker, first download an image of Gremlin Server from Docker Hub:
+
 [source,shell]
 ----
 docker pull tinkerpop/gremlin-server
 ----
 
-The remote connection and basic Gremlin examples can be run on a clean server, which uses the default configuration file
-`conf/gremlin-server.yaml`. To start a clean server, launch a new container with `docker run`:
+Clean server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server
 ----
 
-The traversal examples should be run on a server configured to start with the Modern toy graph, using `conf/gremlin-server-modern.yaml`.
-To start a server with the Modern graph preloaded, launch a new container with `docker run`:
+Modern toy graph server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server conf/gremlin-server-modern.yaml
 ----
 
-Each example can now be run with the following command in their respective project directories:
+The remote connection and basic Gremlin examples can be run on a clean server, while traversal examples should be 
+run on a server with the Modern graph preloaded.
+
+==== Prerequisites
+- Compatible .NET SDK installed (see <<development-environment,Development Environment>> for supported versions)
+
+Navigate to the examples directory:
+
 [source,shell]
 ----
-dotnet run
+cd glv-examples/gremlin-dotnet
+----
+
+Build all projects:
+
+[source,shell]
+----
+dotnet build Examples.sln
+----
+
+Run specific examples:
+
+[source,shell]
+----
+dotnet run --project BasicGremlin
+dotnet run --project Connections  
+dotnet run --project ModernTraversals
 ----
 
 [[gremlin-python]]
@@ -2658,31 +2763,58 @@ async def run_in_thread():
 === Application Examples
 
 The TinkerPop source code contains some sample applications that demonstrate the basics of Gremlin-Python. They
-can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-python/src/main/python/examples/[here]
+can be found in GitHub link:https://github.com/apache/tinkerpop/tree/x.y.z/glv-examples/gremlin-python/[here]
 and are designed to connect to a running <<gremlin-server,Gremlin Server>> configured with the
 `conf/gremlin-server.yaml` and `conf/gremlin-server-modern.yaml` files as included with the standard release packaging.
 
-To run the examples, first download an image of Gremlin Server from Docker Hub:
+This guide assumes Gremlin Server will be executed using Docker. Alternatively, Gremlin Server can run locally (see the <<gremlin-server,Gremlin Server>> documentation for this option).
+
+To start Gremlin Server using Docker, first download an image of Gremlin Server from Docker Hub:
+
 [source,shell]
 ----
 docker pull tinkerpop/gremlin-server
 ----
 
-The remote connection and basic Gremlin examples can be run on a clean server, which uses the default configuration file
-`conf/gremlin-server.yaml`. To start a clean server, launch a new container with `docker run`:
+Clean server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server
 ----
 
-The traversal examples should be run on a server configured to start with the Modern toy graph, using `conf/gremlin-server-modern.yaml`.
-To start a server with the Modern graph preloaded, launch a new container with `docker run`:
+Modern toy graph server:
+
 [source,shell]
 ----
 docker run -d -p 8182:8182 tinkerpop/gremlin-server conf/gremlin-server-modern.yaml
 ----
 
-Each example can now be run with the following commands:
+The remote connection and basic Gremlin examples can be run on a clean server, while traversal examples should be 
+run on a server with the Modern graph preloaded.
+
+==== Prerequisites
+- Compatible Python installed (see <<development-environment,Development Environment>> for supported versions)
+- pip installed
+
+NOTE: On some systems, you may need to use `python3` and `pip3` instead of `python` and `pip`.
+
+Navigate to the examples directory:
+
+[source,shell]
+----
+cd glv-examples/gremlin-python
+----
+
+Install the requirements:
+
+[source,shell]
+----
+pip install -r requirements.txt
+----
+
+Run the examples:
+
 [source,shell]
 ----
 python connections.py

glv-examples/README.md

@@ -0,0 +1,28 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# TinkerPop GLV Examples
+
+This directory contains ready-to-run examples for all Gremlin Language Variants (GLVs) using the latest published driver versions. These examples work out-of-the-box without requiring you to build TinkerPop from source. For detailed instructions on how to run these examples, please refer to the official documentation for each language:
+
+## GLV Examples Documentation
+
+- **Go**: https://tinkerpop.apache.org/docs/current/reference/#gremlin-go-examples
+- **Java**: https://tinkerpop.apache.org/docs/current/reference/#gremlin-java-examples  
+- **JavaScript**: https://tinkerpop.apache.org/docs/current/reference/#gremlin-javascript-examples
+- **.NET**: https://tinkerpop.apache.org/docs/current/reference/#gremlin-dotnet-examples
+- **Python**: https://tinkerpop.apache.org/docs/current/reference/#gremlin-python-examples