tinker-dev
Development guidance for the Apache TinkerPop monorepo. Use when building, testing, or contributing to TinkerPop's graph computing framework and its multi-language Gremlin ecosystem (Java, Python, JavaScript, .NET, Go). Covers coding conventions, build recipes, test evaluation, documentation, development environment setup, and Gremlin MCP server usage.
- License 许可
- Apache-2.0
- 所属仓库
- apache/tinkerpop
- 最近更新
- 2026-11-14
- Stars
- ★ 2.2k
- Forks
- 864
01 前言 Front Matter
- name
- tinker-dev
- license
- Apache-2.0
- metadata
- { "project": "Apache TinkerPop", "version": "1.0.0" }
- description
- Development guidance for the Apache TinkerPop monorepo. Use when building, testing, or contributing to TinkerPop's graph computing framework and its multi-language Gremlin ecosystem (Java, Python, JavaScript, .NET, Go). Covers coding conventions, build recipes, test evaluation, documentation, development environment setup, and Gremlin MCP server usage.
- compatibility
- Requires Java 17, 21, or 25, Maven 3.6.3+, Docker. Individual GLVs may need Python, Node.js, .NET SDK, or Go.
02 资源文件 4
- 参考文档DESIGN.md1.6 KB
- 参考文档references/dev-environment-setup.md3.9 KB
- 参考文档references/gremlin-mcp.md2.8 KB
- 脚本scripts/check-env.sh5.0 KB
03 SKILL.md 正文
TinkerPop Development Skill
Project Overview
Apache TinkerPop is a graph computing framework providing a standard API (the Gremlin graph traversal language) for graph databases and processors. The repository is a Maven multi-module monorepo that wraps JVM code, Python, JavaScript/TypeScript, .NET, and Go under a single build.
Canonical project documentation (prefer local files over external URLs):
README.mdandCONTRIBUTING.mdat the repo root- Reference docs:
docs/src/reference/ - Developer docs:
docs/src/dev/developer/ - Provider docs and Gremlin Semantics:
docs/src/dev/provider/ - IO and Serialization:
docs/src/dev/io/ - Recipes:
docs/src/recipes/ - Upgrade docs:
docs/src/upgrade/ - Future plans:
docs/src/dev/future/
Definition of Done
A change is not done until a full Maven validation has passed locally. Run it before presenting work for review — even when your targeted or unit tests already pass, and even if you judge a full run unnecessary. Incremental testing during development is encouraged, but it does not satisfy this gate.
Validation is two steps. First, rebuild and install the whole reactor so every module picks up your changes:
mvn clean install -DskipTests
Then run verify scoped to what you changed, using the broadest rule that applies, and
always list every module you touched.
Self-contained modules — changing one of these only requires validating that module:
| Changed module | Validate command |
|---|---|
| Python GLV | mvn verify -pl gremlin-python |
| JavaScript GLV | mvn verify -pl :gremlin-javascript |
| .NET GLV | mvn verify -pl :gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests |
| Go GLV | mvn verify -pl :gremlin-go |
gremlint |
mvn verify -pl :gremlint |
gremlin-mcp |
mvn verify -pl :gremlin-mcp |
Other single JVM module (e.g. tinkergraph-gremlin, gremlin-console) |
mvn verify -pl <module> -DskipIntegrationTests=false |
Shared modules — depended on by others, so changing them means validating the consumers too. Use the broadest rule that matches:
gremlin-server,gremlin-driver, orgremlin-utildefine the wire protocol and serialization that every GLV exercises → validate the changed module(s) plus all GLVs:mvn verify -pl <changed>,gremlin-python,:gremlin-javascript,:gremlin-dotnet,:gremlin-dotnet-source,:gremlin-dotnet-tests,:gremlin-go -DskipIntegrationTests=falsegremlin-core,gremlin-test, or anything they depend on ripple across the whole project, including the OLAP engines (hadoop-gremlin,spark-gremlin) → run everything:mvn clean install -DskipIntegrationTests=false- Unsure? Treat it as the
gremlin-corecase and run everything.
Docs or code comments only — no validation gate; this gate is for changes that affect behavior.
Things that quietly invalidate a run
- GLV tests are skipped unless activated. A GLV is built and tested only when its
.glvsentinel exists:gremlin-python/.glv,gremlin-go/.glv, and bothgremlin-dotnet/src/.glvandgremlin-dotnet/test/.glv(JavaScript builds by default). Without the sentinel the module is silently skipped — a green run may have tested nothing of your change. Create the sentinel (or pass-Pglv-python/-Pglv-go) before validating a GLV change. - Grammar and feature-test changes need a reactor build to take effect. The ANTLR grammar
(
gremlin-language/src/main/antlr4/Gremlin.g4) and the Gherkin features undergremlin-testdrive code generation duringmvn clean install— ANTLR parsers, and per-language test code generated from the feature corpus (e.g.gremlin-python/build/generate.groovy, with equivalents for Go, .NET, and JavaScript). After changing either, runmvn clean install -DskipTestsbefore relying on any test, including fast native ones, or you will be testing stale generated code. - Judge pass/fail by the Maven exit code, not console text. Do not
grep/tailthe build output — tests deliberately emit expected errors, so the log misleads. Exit0= pass. For Python, detailed per-suite results are ingremlin-python/target/python3/python-reports/*.xml.
If you cannot run the validation (for example, Docker is unavailable), say so explicitly and report the change as not validated — do not present it as done.
Repository Structure
Most module names map directly to their purpose (gremlin-core, gremlin-server,
gremlin-go, etc.). Two things that aren't obvious:
- The JavaScript workspace lives under
gremlin-js/— it containsgremlin-javascript/(thegremlinnpm driver),gremlin-mcp/, andgremlint/. There is no top-levelgremlin-javascript/directory. - Maven orchestrates the build for every module, including the non-JVM ones (Python, JavaScript, .NET, Go) — which is why the validation in the Definition of Done runs through Maven rather than each language's native test runner.
Cross-language Gherkin feature tests live in gremlin-test/.
Basic Build Commands
Build everything:
mvn clean install
Build a specific module:
mvn clean install -pl <module-name>
For GLV-specific builds and the validation commands per module, see the Definition of Done
table above. For environment setup and GLV activation, see references/dev-environment-setup.md.
Conventions
The general Do/Don't rules and "when in doubt" guidance live in the root AGENTS.md — the
single source of truth, not repeated here. The conventions below are the TinkerPop-specific
ones that are easy to miss:
- License header: every new file needs the ASF header. Canonical text:
bin/asf-license-header.txt. - Test naming: a test using a
GraphProviderwithAbstractGremlinTestis suffixedCheck, notTest. - Gremlin language tests: cross-language behavior is tested with Gherkin features under
gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features/(seedocs/src/dev/developer/for-committers.asciidoc). When adding or changing an intent (And the intent), follow the intent guidance there. - Docs are AsciiDoc under
docs/src/— never Markdown in the main docs tree. For writing or revising any documentation (voice, per-book style, executable code blocks, AsciiDoc wiring), use the tinker-doc skill. The mechanical minimum: add new content to the right book and update itsindex.asciidoc. - Changelog: for user-visible or API changes, add a concise
CHANGELOG.asciidocentry in the correct version section. Do not invent version numbers or release names. Never add the*(breaking)*marker to an entry you write: it is applied only at release, to the lines generated from JIRA issues labelledbreaking(seedocs/src/dev/developer/release.asciidoc), so a hand-written entry without it is correct. Explain a breaking change in the upgrade docs instead. See the tinker-doc skill for changelog discipline (one entry per user-facing change, not per commit) and voice.
Otherwise, match the existing code in neighboring files — explicit imports (no wildcards),
final where practical, SLF4J logging over println, Hamcrest matchers, and closing any
Graph you construct in a test.
Reference Guides
Build and validate commands live in the Definition of Done table above. For the remaining task-specific guidance, see:
- Development Environment Setup — fresh clone to working environment, prerequisites, GLV activation
- Gremlin MCP Server — translation, formatting, querying via MCP
04 同仓库更多 Skills
tinker-review
Graph-based PR review for Apache TinkerPop. Builds a knowledge graph from PR source code, enriches it with semantic relationships guided by domain playbooks, runs structural analysis, and produces an HTML evidence package. Use when asked to review a TinkerPop PR by number.
tinker-merge
Merge work forward through Apache TinkerPop's release branches toward master (e.g. 3.7-dev, then 3.8-dev, then master), testing each branch locally and stopping before the push. Use only when the operator explicitly asks to merge a pull request, a feature branch, or commits already on a release branch.
tinker-doc
Writing, editing and reviewing documentation for the Apache TinkerPop project. Use when authoring or revising any content under docs/src/ — reference docs, recipes, tutorials, upgrade/release notes, provider and developer guides — or the CHANGELOG. Covers the TinkerPop documentation voice and the per-book style expectations, the executable Gremlin code-block pipeline, and AsciiDoc conventions. For building and validating code changes, see tinker-dev.