This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 8ea9033f322dcc804b126e5a6a3a6774eac55764 Author: Stephen Mallette <[email protected]> AuthorDate: Sun Aug 9 08:27:25 2026 -0400 Rewrite AGENTS.md on 3.7-dev around the Agent Skills Replaces the inlined build recipes and repository tour with pointers to the tinker-dev and tinker-doc skills, matching master. Adds what master has no need for: the non-breaking constraint that governs a 3.7.x change. The per-module gremlin-python/AGENTS.md goes away with it. Assisted-by: Claude Code:claude-opus-5 --- AGENTS.md | 324 ++++++++++++++++------------------------------- gremlin-python/AGENTS.md | 105 --------------- 2 files changed, 106 insertions(+), 323 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 04ddbad2e1..1e8286b331 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,250 +1,138 @@ # 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. +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. -- `README.md` -- `CONTRIBUTING.md` -- Developer documentation at `docs/src/dev/**` - -This file must not contradict those documents. If it appears to, treat them as canonical and update this file -accordingly. - -## Licensing and Provenance - -Apache TinkerPop is licensed under Apache License 2.0. Contributions must meet the -[ASF's Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html). 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 to - the commit message, for example: `Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]`. 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. - -## 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](SECURITY.md), which -points to [THREAT_MODEL.md](THREAT_MODEL.md). Consult it before triaging or reporting security issues. - -*** - -## 1. Project overview - -Key project docs (prefer these local files over external URLs): - -- Reference docs: `docs/src/reference/**` -- Recipes: `docs/src/recipes/**` -- Upgrade docs: `docs/src/upgrade/**` -- IO and Serialization docs: `docs/src/dev/io/**` -- Provider docs and Gremlin Semantics: `docs/src/dev/provider/**` -- Developer docs: `docs/src/dev/developer/**` -- Future plans: `docs/src/dev/future/**` - -The project website mirrors these for released versions; use local files for branch‑accurate information. - -*** - -## 2. Repository structure (high level) - -Use these as anchors when exploring the repo: - -- Core code and modules: Maven multi‑module layout under the repo root, though modules may not contain JVM-relevant code - (i.e. Maven is simply the build orchestration tool wrapping other environments like Python or Go) -- Docs: `docs/src/**` (AsciiDoc “books”, reference, dev docs, recipes, etc.) -- Changelog: `CHANGELOG.asciidoc` -- Website: `docs/site/**` -- Scripts: - - Docker scripts: `docker/*.sh` - - Docs/site scripts: `bin/process-docs.sh`, `bin/generate-home.sh` - -When adding or modifying files, follow the existing structure and conventions in the surrounding directory. - -*** - -## 3. Nested AGENTS.md files - -This repository uses additional `AGENTS.md` files in certain subdirectories (for example, -`gremlin-python/AGENTS.md`, `gremlin-dotnet/AGENTS.md`, etc.) to provide stack‑specific guidance. - -Agents should: - -- Always read this root `AGENTS.md` for global rules. -- When working in a subdirectory, also look for the closest `AGENTS.md` in the current or parent -directories and apply its instructions for that area. -- Treat more specific `AGENTS.md` files (deeper in the tree) as overriding or refining the generic -guidance here when there is a conflict. +## This Branch: 3.7-dev -## 4. Build and test recipes +`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`. -### 4.1 Basic build and test +## Primary Guidance: Agent Skills -- Build everything: +This repository provides development guidance as [Agent Skills](https://agentskills.io): +`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. - ```bash - mvn clean install - ``` +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. -- Build a specific module: +## Planning and Memory: Beads - ```bash - mvn clean install -pl <module-name> - ``` +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. - Example: - - ```bash - mvn clean install -pl tinkergraph-gremlin - ``` - -### 4.2 Integration and specialized builds - -- Enable integration tests: - - ```bash - mvn clean install -DskipIntegrationTests=false - ``` - -- Include Neo4j tests: - - ```bash - mvn clean install -DincludeNeo4j - ``` - -### 4.3 Gremlin Language Variant (GLV) builds - -Build Gremlin Server first: +**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. ```bash -mvn clean install -pl :gremlin-server -am -DskipTests +command -v bd >/dev/null && bd prime ``` -Each GLV has its own module structure: - -- Python: - - ```bash - mvn clean install -Pglv-python -pl gremlin-python - ``` - -- .NET: - - ```bash - mvn clean install -pl gremlin-dotnet,gremlin-dotnet-source,gremlin-dotnet-tests - ``` - -- JavaScript: - - ```bash - mvn clean install -Pglv-js -pl gremlin-javascript - ``` - -- Go: - - ```bash - mvn clean install -Pglv-go -pl gremlin-go - ``` +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 -## 5. Documentation +These local documents are authoritative. If this file appears to contradict them, treat them as canonical. -TinkerPop’s documentation is AsciiDoc‑based and lives under `docs/src/**`. - -When adding or updating docs: - -- Use AsciiDoc (not Markdown) in the main docs tree. -- Place new content in the appropriate book (reference, dev, recipes, etc.). -- Update the relevant `index.asciidoc` so the new content is included in the build. - -*** +- `README.md` +- `CONTRIBUTING.md` +- Developer documentation at `docs/src/dev/**` -## 6. Coding and testing conventions +## Licensing and Provenance -Agents should follow these conventions when generating or editing code and tests. +Apache TinkerPop is licensed under Apache License 2.0. Contributions must meet the +[ASF's Generative Tooling guidance](https://www.apache.org/legal/generative-tooling.html). In particular: -### 6.1 Code style +* *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. -- All files should include the Apache Software Foundation license header - canonical text for the header is at `bin/asf-license-header.txt`. -- Do **not** use import wildcards (for example, avoid `import org.apache.tinkerpop.gremlin.structure.*`); prefer explicit imports. -- Respect existing naming patterns and package organization. -- Define variables as `final` whenever possible, except for loop variables. +## Definition of Done -### 6.2 Test guidelines +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. -- Prefer SLF4J `Logger` for output instead of `System.out.println` or `println` in tests. -- Use `TestHelper` utilities to create temporary directories and file structures for file‑based tests, instead of hard‑coding paths. -- Always close `Graph` instances that are manually constructed in tests. -- Tests using a `GraphProvider` implementation with `AbstractGremlinTest` should be suffixed with `Check` instead of `Test`. -- Prefer Hamcrest matchers for boolean‑style assertions (for example, `assertThat(..., is(true))`) instead of manually checking booleans. -- For Gremlin language tests, see the "Gremlin Language Test Cases" section of `docs/src/dev/developer/for-committers.asciidoc` -for more details and use Gherkin tests under: +Match the validation to your changeset using a two-step pattern: - ```text - gremlin-tests/src/main/resources/org/apache/tinkerpop/gremlin/test/features - ``` +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: -## 7. Changelog, license, and checks +- 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` -When changes affect behavior, APIs, or user‑visible features: +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**. -- Add or update entries in `CHANGELOG.asciidoc` in the correct version section. -- Do not invent new version numbers or release names; follow the existing pattern. -- Preserve and respect license headers and notices in all files. -- Avoid adding third‑party code or dependencies with incompatible licenses. +## Essential Rules -*** +These rules apply to any AI/IDE assistant operating on this repository. -## 8. Do and don’t for agents +### 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. -These rules apply to any AI/IDE assistant operating on this repository. +## Security -### 8.1 Do - -- **Do** make small, focused changes that are easy to review. -- **Do** run the relevant build and test commands before suggesting that a change is complete. -- **Do** update or add tests when behavior changes. -- **Do** update documentation and/or changelog when you change public behavior or APIs. -- **Do** follow existing patterns for code structure, documentation layout, and naming. -- **Do** point maintainers to relevant documentation or issues when proposing non‑trivial changes. -- **Do** stop to ask human to commit, push or merge manually, when code is ready. - -### 8.2 Don’t - -- **Don’t** perform large, sweeping refactors (across many modules or files) unless explicitly requested. -- **Don’t** change public APIs, configuration formats, or network protocols without explicit human approval and associated design/issue. -- **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 an associated discussion and issue. -- **Don’t** invent project policies, version numbers, or release names. -- **Don’t** remove or weaken tests to “fix” failures; adjust the implementation or the test data instead. -- **Don't** push to any branch. -- **Don't** merge any PR or branch. -- **Don't** create tags or releases. - -If you are uncertain about the impact of a change, prefer to: - -- Make a minimal patch. -- Add comments or notes for reviewers. -- Ask for clarification. - -*** - -## 9. When in doubt - -If AGENTS.md does not clearly cover a situation: - -1. Look for relevant information in: - - `CONTRIBUTING.md` - - Developer docs under `docs/src/dev/developer/**` - - Reference docs and recipes -2. Prefer **no change** over an unsafe or speculative change. -3. Surface the question to human maintainers (for example, by leaving a comment, or drafting a minimal PR that asks for guidance). - -This file is intended to help tools act like a careful, well‑informed contributor. When in doubt, defer to human -judgment and the canonical project documentation. +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](SECURITY.md), which +points to [THREAT_MODEL.md](THREAT_MODEL.md). Consult it before triaging or reporting security issues. diff --git a/gremlin-python/AGENTS.md b/gremlin-python/AGENTS.md deleted file mode 100644 index c86234a331..0000000000 --- a/gremlin-python/AGENTS.md +++ /dev/null @@ -1,105 +0,0 @@ -### gremlin-python AGENTS.md - -This document provides stack-specific guidance for developers and AI agents working on the `gremlin-python` module. It -supplements the root `AGENTS.md` file. - ---- - -### 1. Build and Test Requirements - -To build and run tests for `gremlin-python`, ensure the following: - -* **Python Version**: A supported Python version must be installed. `gremlin-python` supports Python 3.9 through - 3.13. -* **Virtual Environment**: While a virtual environment is recommended for local development, the preferred way to - run tests is via Maven and Docker, which handles environment isolation automatically. -* **Docker**: Docker and Docker Compose must be installed and running. -* **Maven**: Maven must be installed. - -### 2. Preferred Build Orchestration - -The preferred way to run tests is via Maven from the repository root. This ensures an OS-agnostic execution environment -and handles all dependencies, including starting the Gremlin Server. - -* **Run all tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python - ``` - -* **Run only Unit Tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/unit" - ``` - -* **Run only Integration Tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="tests/integration" - ``` - -* **Run only Feature Tests**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DradishArgs=" " - ``` - -### 3. Targeted Test Execution - -You can pass arguments to `pytest` or `radish` via Maven properties to run specific tests. - -* **Run a specific Unit/Integration test**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DpytestArgs="-k test_name" - ``` - -* **Run Feature tests with specific tags**: - ```bash - mvn clean install -pl gremlin-python -Pglv-python -DradishArgs="-t @some_tag" - ``` - -### 4. Evaluating Build Results - -**DO NOT** use `grep`, `tail` or similar text-search tools on the Maven console output (or `.output.txt`) to determine -if the tests passed or failed. The Maven output can be misleading due to the tests validating expected errors. - -To accurately evaluate the results, follow this strict hierarchy: - -1. **Check the Command Exit Code**: A successful build **must** exit with code `0`. Any non-zero exit code is a failure. -2. **Verify via XML Reports**: If the build fails (non-zero exit) you **must** inspect the JUnit XML reports in `gremlin-python/target/python3/python-reports/`: - * `TEST-native-python.xml` (Unit/Integration tests) - * `feature-graphbinary-result.xml` (Feature tests - GraphBinary) - * `feature-graphson-result.xml` (Feature tests - GraphSON) - -Feature test XML reports will not be present if the unit/integration tests fail. - -**DO NOT** attempt to investigate a build failure beyond reporting what failed unless asked. - -### 5. Manual Test Execution (Advanced) - -If you must run tests manually outside Maven, follow these steps from the `gremlin-python/src/main/python/` directory. - -#### 5.1 Environment Setup -```bash -python3 -m venv .venv -source .venv/bin/activate -pip install --upgrade pip -pip install .[test,kerberos] -``` - -#### 5.2 Gremlin Server Management - -Manual integration and feature tests require a running Gremlin Server. Run these from `gremlin-python/`: -```bash -# Start/Restart server -docker compose down gremlin-server-test-python -docker compose up -d gremlin-server-test-python - -# Check status (wait for healthy) -docker compose ps gremlin-server-test-python -``` - -#### 5.3 Running Tests Manually -* **Unit Tests**: `pytest tests/unit/` -* **Integration Tests**: `pytest tests/integration/` -* **Feature Tests**: - ```bash - radish -f dots -e -t -b ./tests/radish ../../../../gremlin-test/src/main/resources/org/apache/tinkerpop/gremlin/test/features --user-data='serializer=application/vnd.gremlin-v3.0+json' - ``` \ No newline at end of file
