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 b63eff5f5ceff9aaea595a0a63b3640fbcd6b167 Author: Stephen Mallette <[email protected]> AuthorDate: Tue Feb 17 08:45:45 2026 -0500 Added AGENTS.md to gremlin-python Should help agents to be a bit smarter with builds and spend less time in churn. CTR --- AGENTS.md | 41 ++++++++++------ gremlin-python/AGENTS.md | 120 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 147 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 18b82387de..fb83e7660f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,11 +67,24 @@ When adding or modifying files, follow the existing structure and conventions in *** -## 3. Build and test recipes +## 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. + +## 4. Build and test recipes These commands are the **preferred** way for agents and contributors to build and test. -### 3.1 Basic build and test +### 4.1 Basic build and test - Build everything: @@ -91,7 +104,7 @@ These commands are the **preferred** way for agents and contributors to build an mvn clean install -pl tinkergraph-gremlin ``` -### 3.2 Integration and specialized builds +### 4.2 Integration and specialized builds - Enable integration tests: @@ -105,7 +118,7 @@ These commands are the **preferred** way for agents and contributors to build an mvn clean install -DincludeNeo4j ``` -### 3.3 Gremlin Language Variant (GLV) builds +### 4.3 Gremlin Language Variant (GLV) builds Build Gremlin Server first: @@ -141,7 +154,7 @@ Each GLV has its own module structure: *** -## 4. Documentation and site +## 5. Documentation and site TinkerPop’s documentation is AsciiDoc‑based and lives under `docs/src/**`. @@ -153,17 +166,17 @@ When adding or updating docs: *** -## 5. Coding and testing conventions +## 6. Coding and testing conventions Agents should follow these conventions when generating or editing code and tests. -### 5.1 Code style +### 6.1 Code style - Match the existing style in nearby code. - Do **not** use import wildcards (for example, avoid `import org.apache.tinkerpop.gremlin.structure.*`); prefer explicit imports. - Respect existing naming patterns and package organization. -### 5.2 Test guidelines +### 6.2 Test guidelines - 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. @@ -177,7 +190,7 @@ for more details and use Gherkin tests under: gremlin-tests/src/main/resources/org/apache/tinkerpop/gremlin/test/features ``` -### 5.3 Deprecation +### 6.3 Deprecation When deprecating code: @@ -194,7 +207,7 @@ issue. *** -## 6. Changelog, license, and checks +## 7. Changelog, license, and checks When changes affect behavior, APIs, or user‑visible features: @@ -205,11 +218,11 @@ When changes affect behavior, APIs, or user‑visible features: *** -## 7. Do and don’t for agents +## 8. Do and don’t for agents These rules apply to any AI/IDE assistant operating on this repository. -### 7.1 Do +### 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. @@ -218,7 +231,7 @@ These rules apply to any AI/IDE assistant operating on this repository. - **Do** follow existing patterns for code structure, documentation layout, and naming. - **Do** point maintainers to relevant documentation or issues when proposing non‑trivial changes. -### 7.2 Don’t +### 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. @@ -235,7 +248,7 @@ If you are uncertain about the impact of a change, prefer to: *** -## 8. When in doubt +## 9. When in doubt If AGENTS.md does not clearly cover a situation: diff --git a/gremlin-python/AGENTS.md b/gremlin-python/AGENTS.md new file mode 100644 index 0000000000..0021750bc8 --- /dev/null +++ b/gremlin-python/AGENTS.md @@ -0,0 +1,120 @@ +<!-- +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. +--> +### 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**: Python 3.9 or higher must be installed. +* **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
