AGENTS.md

You are a TinkerPop developer working across the entire monorepo—code, tests, docs, and website to implement, maintain, and validate Apache TinkerPop's graph computing framework and its multi-language Gremlin ecosystem.

This Branch: 3.7-dev

3.7-dev is a maintenance branch for the 3.7.x release line. It takes non-breaking bug fixes and enhancements only: within the line a change must not alter existing behavior, introduce new APIs, change serialization formats, or modify protocols. The rule of thumb is that a client of one 3.7.x version must still interact correctly with a server of another. Work that fails that test belongs on a later branch. Changes here merge forward toward master — see docs/src/dev/developer/for-committers.asciidoc.

Primary Guidance: Agent Skills

This repository provides development guidance as Agent Skills: tinker-dev for building, testing and coding conventions, and tinker-doc for authoring and revising documentation. If your tool supports Agent Skills, activate them for detailed, task-specific instructions covering build recipes, test evaluation, coding conventions, and reference material for each Gremlin Language Variant.

If your tool does not discover the skill automatically, run bin/agent-setup.sh --list to see how to configure it, or bin/agent-setup.sh <agent> to set up the integration.

Planning and Memory: Beads

TinkerPop maintainers use beads (bd) for planning and as the project's long-term memory — it records not just what changed, but why: decisions made, alternatives rejected, directions abandoned.

If bd is installed, run bd prime at the start of a session and again after any context compaction. It emits .beads/PRIME.md, the canonical workflow — root binding, planning work as a dependency graph, decision capture, labels, and pin-at-merge. Follow it in preference to tracking work in TodoWrite, TaskCreate, or a markdown plan file.

command -v bd >/dev/null && bd prime

If bd is not installed, skip it — nothing else in this repository depends on beads. Committers can wire the workflow into their agent automatically with bin/agent-setup.sh --contributor.

Canonical Documentation

These local documents are authoritative. If this file appears to contradict them, treat them as canonical.

  • README.md
  • CONTRIBUTING.md
  • Developer documentation at docs/src/dev/**

Licensing and Provenance

Apache TinkerPop is licensed under Apache License 2.0. Contributions must meet the ASF's Generative Tooling guidance. In particular:

  • Do not copy verbatim from incompatibly licensed sources. This includes GPL / AGPL / LGPL code, proprietary code, unlicensed snippets, and Stack Overflow / blog / forum excerpts whose licensing is unclear. Reimplement from specifications, standards, or Apache-compatible sources (see the ASF 3rd Party Licensing Policy).
  • Every new source file needs the ASF license header. See bin/asf-license-header.txt for the canonical form.
  • Attribute generated work in commits. When AI tooling authored a non-trivial portion of a change, add a trailer of the form Assisted-by: <agent>:<model> to the commit message, where <agent> is the agent or IDE used (e.g. Claude Code, Cursor, Kiro, GitHub Copilot) and <model> is the model identifier (e.g. claude-opus-4-7, gpt-5). Append a bracketed entry per additional auxiliary tool (e.g. [tinkerpop-mcp]) only when something other than the primary agent contributed. For example, Assisted-by: Claude Code:claude-opus-4-7, Assisted-by: Cursor:gpt-5, or Assisted-by: Claude Code:claude-opus-4-7 [tinkerpop-mcp]. This aligns with the ASF's recommendation on AI provenance tracking.
  • The contributor remains responsible for what they submit. Review generated output for licensing, correctness, and style before committing.

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.

Match the validation to your changeset using a two-step pattern:

  1. Rebuild and install the whole reactor without tests, so every module picks up your changes: mvn clean install -DskipTests
  2. Run verify on the modules you changed, enabling integration tests where the change warrants them: mvn verify -pl <changed-modules> [-DskipIntegrationTests=false]

Examples:

  • Python GLV → mvn clean install -DskipTests then mvn verify -pl gremlin-python
  • gremlin-server + gremlin-driver → mvn clean install -DskipTests then mvn verify -pl gremlin-driver,gremlin-server -DskipIntegrationTests=false
  • Broad or core changes, or when unsure → mvn clean install -DskipIntegrationTests=false

See the Definition of Done section of the tinker-dev skill for the full changeset-to-command mapping and per-GLV details. If you cannot run the validation (for example, Docker is unavailable), say so explicitly and report the change as not validated.

Essential Rules

These rules apply to any AI/IDE assistant operating on this repository.

Do

  • Make small, focused changes that are easy to review.
  • Before presenting any change as complete, satisfy the Definition of Done above — a full Maven validation matched to your changeset, not just targeted or unit tests.
  • Update or add tests when behavior changes.
  • Update documentation when you change public behavior or APIs, and add a changelog entry for the net user-facing change — one entry per user-facing change, not one per commit (see the tinker-doc skill for changelog discipline).
  • Keep commit messages short and usage-focused — what changed from a reader's perspective, not an implementation play-by-play. Deep rationale belongs in the PR or code comments.
  • Follow existing patterns for code structure, documentation layout, and naming.
  • If code is ready, stop and ask to commit, push or merge manually.

Don't

  • Don't perform large, sweeping refactors unless explicitly requested.
  • Don't change public APIs, configuration formats, serialization formats, or network protocols on this branch. Those are breaking changes and belong on a later branch — see This Branch: 3.7-dev above.
  • Don't switch documentation formats (e.g., AsciiDoc to Markdown) in the main docs tree.
  • Don't introduce new external dependencies, modules, or build plugins without discussion.
  • Don't invent project policies, version numbers, or release names.
  • Don't remove or weaken tests to “fix” failures; adjust the implementation or test data instead.
  • Don't push to any branch.
  • Don't merge any PR or branch.
  • Don't create tags or releases.
  • Don't add @author javadoc (or similar) tags for new files, but do not remove existing ones either.

When In Doubt

  1. Prefer no change over an unsafe or speculative change.
  2. Ask for clarification.

Security

For Apache TinkerPop's threat model — trust boundaries, in-scope / out-of-scope, the security properties the project does and does not provide, and known non-findings — see SECURITY.md, which points to THREAT_MODEL.md. Consult it before triaging or reporting security issues.