Skip to content

Commit 59a2d02

Browse files
spmallettespmallette
authored
Merge pull request #3380 from apache/agent-skills
Added tinkerpop-dev skills based on Agent Skills standard
2 parents 10378a7 + 7711c14 commit 59a2d02

19 files changed

Lines changed: 1580 additions & 591 deletions

File tree

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,11 @@ coverage.out
4848
gremlinconsoletest.egg-info
4949
CLAUDE.md
5050
**/.claude/
51+
.kiro/
52+
.agents/
53+
.cursor/
54+
.codex/
55+
.github/skills/
5156
.beads/
5257
gremlin-python/src/main/python/build/
5358
node_modules/

‎.skills/tinkerpop-dev/SKILL.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
name: tinkerpop-dev
3+
description: >
4+
Development guidance for the Apache TinkerPop monorepo. Use when building,
5+
testing, or contributing to TinkerPop's graph computing framework and its
6+
multi-language Gremlin ecosystem (Java, Python, JavaScript, .NET, Go).
7+
Covers coding conventions, build recipes, test evaluation, documentation,
8+
development environment setup, and Gremlin MCP server usage.
9+
license: Apache-2.0
10+
compatibility: Requires Java 11+, Maven 3.5.3+, Docker. Individual GLVs may need Python, Node.js, .NET SDK, or Go.
11+
metadata:
12+
version: 1.0.0
13+
project: Apache TinkerPop
14+
---
15+
16+
# TinkerPop Development Skill
17+
18+
## Project Overview
19+
20+
Apache TinkerPop is a graph computing framework providing a standard API (the Gremlin graph
21+
traversal language) for graph databases and processors. The repository is a Maven multi-module
22+
monorepo that wraps JVM code, Python, JavaScript/TypeScript, .NET, and Go under a single build.
23+
24+
Canonical project documentation (prefer local files over external URLs):
25+
26+
- `README.md` and `CONTRIBUTING.md` at the repo root
27+
- Reference docs: `docs/src/reference/`
28+
- Developer docs: `docs/src/dev/developer/`
29+
- Provider docs and Gremlin Semantics: `docs/src/dev/provider/`
30+
- IO and Serialization: `docs/src/dev/io/`
31+
- Recipes: `docs/src/recipes/`
32+
- Upgrade docs: `docs/src/upgrade/`
33+
- Future plans: `docs/src/dev/future/`
34+
35+
## Repository Structure
36+
37+
```
38+
tinkerpop/
39+
├── gremlin-core/ Core graph API and traversal engine (Java)
40+
├── gremlin-server/ Gremlin Server (Java)
41+
├── tinkergraph-gremlin/ In-memory reference graph (Java)
42+
├── gremlin-python/ Python GLV
43+
├── gremlin-js/ JavaScript/TypeScript workspace root
44+
│ ├── gremlin-javascript/ JS driver (npm: "gremlin")
45+
│ ├── gremlin-mcp/ Gremlin MCP server (npm: "gremlin-mcp")
46+
│ └── gremlint/ Gremlin query formatter (npm: "gremlint")
47+
├── gremlin-dotnet/ .NET GLV
48+
├── gremlin-go/ Go GLV
49+
├── gremlin-test/ Shared test resources and Gherkin features
50+
├── gremlin-tools/ Benchmarks, coverage, socket server
51+
├── docs/src/ AsciiDoc documentation
52+
├── docker/ Docker build scripts and configs
53+
├── bin/ Utility scripts
54+
└── CHANGELOG.asciidoc Changelog
55+
```
56+
57+
Maven is the build orchestration tool for all modules, including non-JVM ones.
58+
59+
## Basic Build Commands
60+
61+
Build everything:
62+
```bash
63+
mvn clean install
64+
```
65+
66+
Build a specific module:
67+
```bash
68+
mvn clean install -pl <module-name>
69+
```
70+
71+
For GLV-specific builds, test execution, and advanced workflows, see the appropriate
72+
reference file under `references/`.
73+
74+
## Coding Conventions
75+
76+
- All files must include the Apache Software Foundation license header. Canonical text
77+
is at `bin/asf-license-header.txt`.
78+
- Do not use import wildcards (e.g., avoid `import org.apache.tinkerpop.gremlin.structure.*`).
79+
Use explicit imports.
80+
- Define variables as `final` whenever possible, except for loop variables.
81+
- Respect existing naming patterns and package organization.
82+
- Use `@/` path aliases for JavaScript/TypeScript imports where the project uses them.
83+
84+
## Test Conventions
85+
86+
- Prefer SLF4J `Logger` over `System.out.println` or `println` in tests.
87+
- Use `TestHelper` utilities for temporary directories and file structures instead of
88+
hard-coding paths.
89+
- Always close `Graph` instances that are manually constructed in tests.
90+
- Tests using a `GraphProvider` with `AbstractGremlinTest` should be suffixed `Check`,
91+
not `Test`.
92+
- Prefer Hamcrest matchers for boolean assertions (e.g., `assertThat(..., is(true))`)
93+
instead of manually checking booleans.
94+
- Gremlin language tests use Gherkin features under:
95+
`gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features/`
96+
See `docs/src/dev/developer/for-committers.asciidoc` for details.
97+
98+
## Documentation Conventions
99+
100+
- TinkerPop documentation is AsciiDoc-based under `docs/src/`. Do not use Markdown in
101+
the main docs tree.
102+
- Place new content in the appropriate book (reference, dev, recipes, etc.).
103+
- Update the relevant `index.asciidoc` so new content is included in the build.
104+
- For detailed documentation generation instructions, see `references/documentation.md`.
105+
106+
## Changelog, License, and Checks
107+
108+
When changes affect behavior, APIs, or user-visible features:
109+
110+
- Add or update entries in `CHANGELOG.asciidoc` in the correct version section.
111+
- Do not invent new version numbers or release names; follow the existing pattern.
112+
- Preserve and respect license headers and notices in all files.
113+
- Avoid adding third-party code or dependencies with incompatible licenses.
114+
115+
## Agent Guardrails
116+
117+
### Do
118+
119+
- Make small, focused changes that are easy to review.
120+
- Run the relevant build and test commands before suggesting a change is complete.
121+
- Update or add tests when behavior changes.
122+
- Update documentation and/or changelog when changing public behavior or APIs.
123+
- Follow existing patterns for code structure, documentation layout, and naming.
124+
- Point maintainers to relevant documentation or issues when proposing non-trivial changes.
125+
126+
### Don't
127+
128+
- Don't perform large, sweeping refactors unless explicitly requested.
129+
- Don't change public APIs, configuration formats, or network protocols without explicit
130+
human approval and an associated design/issue.
131+
- Don't switch documentation formats (e.g., AsciiDoc to Markdown) in the main docs tree.
132+
- Don't introduce new external dependencies, modules, or build plugins without an
133+
associated discussion and issue.
134+
- Don't invent project policies, version numbers, or release names.
135+
- Don't remove or weaken tests to "fix" failures; adjust the implementation or test
136+
data instead.
137+
138+
If uncertain about the impact of a change, prefer to make a minimal patch, add comments
139+
for reviewers, and ask for clarification.
140+
141+
## When In Doubt
142+
143+
1. Check `CONTRIBUTING.md`, developer docs under `docs/src/dev/developer/`, and reference docs.
144+
2. Prefer no change over an unsafe or speculative change.
145+
3. Surface the question to human maintainers.
146+
147+
## Reference Guides
148+
149+
For deeper, task-specific guidance, see the reference files in this skill:
150+
151+
- [Development Environment Setup](references/dev-environment-setup.md) — fresh clone to working environment
152+
- [Java / Core Builds](references/build-java.md) — Java modules, gremlin-server, integration tests
153+
- [Python GLV](references/build-python.md) — build, test, result evaluation
154+
- [JavaScript GLV](references/build-javascript.md) — npm workspace, build, test, evaluation
155+
- [.NET GLV](references/build-dotnet.md) — build, test, Docker setup
156+
- [Go GLV](references/build-go.md) — build, test, Docker setup
157+
- [Documentation](references/documentation.md) — AsciiDoc generation, website
158+
- [Gremlin MCP Server](references/gremlin-mcp.md) — translation, formatting, querying via MCP

‎.skills/tinkerpop-dev/references/build-dotnet.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
# .NET GLV Build and Test
21+
22+
## Requirements
23+
24+
- **.NET SDK 8.0+** — optional; Docker handles test execution via Maven.
25+
- **Docker and Docker Compose** — required for running tests through Maven.
26+
- **Maven** — preferred build orchestration.
27+
- **Mono** — only needed for packing the `Gremlin.Net.Template` project.
28+
29+
## Module Structure
30+
31+
```
32+
gremlin-dotnet/
33+
├── pom.xml Maven parent (packaging=pom)
34+
├── Gremlin.Net.sln .NET solution file
35+
├── src/ Source code (Gremlin.Net library + template)
36+
│ ├── .glv Sentinel file to activate build
37+
│ └── Gremlin.Net/ Main library
38+
├── test/ Test projects
39+
│ ├── .glv Sentinel file to activate tests
40+
│ ├── Gremlin.Net.UnitTest/
41+
│ ├── Gremlin.Net.IntegrationTest/
42+
│ ├── Gremlin.Net.Benchmarks/
43+
│ └── Gremlin.Net.Template.IntegrationTest/
44+
├── Examples/ Example projects
45+
└── docker-compose.yml Test infrastructure
46+
```
47+
48+
## Activation
49+
50+
Both `src` and `test` directories need `.glv` sentinel files:
51+
```bash
52+
touch gremlin-dotnet/src/.glv
53+
touch gremlin-dotnet/test/.glv
54+
```
55+
56+
Without these files, TinkerPop still builds with Maven but .NET projects are skipped.
57+
58+
## Maven Build Commands
59+
60+
Run from the repository root.
61+
62+
Build and test (requires Docker):
63+
```bash
64+
mvn clean install -pl :gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests
65+
```
66+
67+
The test execution uses Docker Compose to:
68+
1. Start a Gremlin Server test container (`gremlin-server-test-dotnet`)
69+
2. Run `dotnet test ./Gremlin.Net.sln -c Release` inside a .NET SDK 8.0 container
70+
3. Run example projects to verify they work
71+
4. Tear down containers
72+
73+
## Docker Test Infrastructure
74+
75+
The `docker-compose.yml` defines:
76+
- `gremlin-server-test-dotnet` — Gremlin Server on ports 45940-45942 and 4588
77+
- `gremlin-dotnet-integration-tests` — .NET SDK 8.0 container that runs `dotnet test`
78+
79+
The test container uses `dotnet-trx` for test result reporting.
80+
81+
## Test Results
82+
83+
Test results are written as `.trx` files inside the container. On failure, check the
84+
Maven console output for the `dotnet test` exit code and error summary.
85+
86+
## Template Packaging
87+
88+
To pack the `Gremlin.Net.Template` NuGet package (requires Mono):
89+
```bash
90+
mvn clean install -Dnuget
91+
```
92+
93+
## Evaluating Build Results
94+
95+
Use the Maven exit code to determine pass/fail:
96+
- Exit `0` — success
97+
- Non-zero — failure; check the `dotnet test` output in the Maven console

‎.skills/tinkerpop-dev/references/build-go.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<!--
2+
Licensed to the Apache Software Foundation (ASF) under one
3+
or more contributor license agreements. See the NOTICE file
4+
distributed with this work for additional information
5+
regarding copyright ownership. The ASF licenses this file
6+
to you under the Apache License, Version 2.0 (the
7+
"License"); you may not use this file except in compliance
8+
with the License. You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing,
13+
software distributed under the License is distributed on an
14+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
KIND, either express or implied. See the License for the
16+
specific language governing permissions and limitations
17+
under the License.
18+
-->
19+
20+
# Go GLV Build and Test
21+
22+
## Requirements
23+
24+
- **Go 1.25+** — optional for local development; Docker handles test execution via Maven.
25+
- **Docker and Docker Compose** — required for running tests through Maven.
26+
- **Maven** — preferred build orchestration.
27+
28+
## Module Structure
29+
30+
```
31+
gremlin-go/
32+
├── pom.xml Maven module (no Java source; Maven wraps Go)
33+
├── go.mod Go module definition
34+
├── go.sum Go dependency checksums
35+
├── run.sh Convenience script for Docker-based testing
36+
├── driver/ Go driver source and tests
37+
│ ├── cucumber/ BDD feature test support
38+
│ ├── resources/ Test resources
39+
│ └── *.go / *_test.go Source and test files
40+
├── examples/ Example programs
41+
└── docker-compose.yml Test infrastructure
42+
```
43+
44+
## Activation
45+
46+
Create a `.glv` sentinel file to include Go in standard builds:
47+
```bash
48+
touch gremlin-go/.glv
49+
```
50+
51+
Without this file, TinkerPop still builds with Maven but Go is skipped.
52+
53+
## Maven Build Commands
54+
55+
Run from the repository root.
56+
57+
Build and test (requires Docker):
58+
```bash
59+
mvn clean install -Pglv-go -pl :gremlin-go
60+
```
61+
62+
The Maven build uses Docker Compose to:
63+
1. Start a Gremlin Server test container
64+
2. Run `go test -v -json ./... -race -covermode=atomic` inside a Go container
65+
3. Run example programs
66+
4. Tear down containers and prune dangling images
67+
68+
## Convenience Script
69+
70+
From `gremlin-go/`:
71+
```bash
72+
./run.sh # Uses current project version
73+
./run.sh 4.0.0-SNAPSHOT # Specify server version
74+
./run.sh 3.8.0 # Use a released version
75+
```
76+
77+
The default requires a SNAPSHOT server image built with:
78+
```bash
79+
mvn clean install -pl :gremlin-server -DskipTests -DskipIntegrationTests=true -am
80+
mvn install -Pdocker-images -pl :gremlin-server
81+
```
82+
83+
## Docker Test Infrastructure
84+
85+
The `docker-compose.yml` defines:
86+
- `gremlin-server-test` — Gremlin Server on ports 45940-45942 and 4588
87+
- `gremlin-go-integration-tests` — Go 1.25 container that runs tests with race
88+
detection, coverage, and `gotestfmt` for formatted output
89+
90+
Environment variables in the test container:
91+
- `CUCUMBER_FEATURE_FOLDER` — path to Gherkin feature files
92+
- `GREMLIN_SERVER_URL` — server endpoint for integration tests
93+
- `RUN_INTEGRATION_TESTS=true`
94+
- `RUN_BASIC_AUTH_INTEGRATION_TESTS=true`
95+
96+
## Local Development
97+
98+
After installing Go locally:
99+
```bash
100+
cd gremlin-go
101+
go build ./...
102+
go test ./driver/ -run TestName
103+
```
104+
105+
For integration tests, a running Gremlin Server is required.
106+
107+
## Evaluating Build Results
108+
109+
Use the Maven exit code to determine pass/fail:
110+
- Exit `0` — success
111+
- Non-zero — failure; check the `go test` output in the Maven console

0 commit comments

Comments
 (0)