spmallette commented on code in PR #3305: URL: https://github.com/apache/tinkerpop/pull/3305#discussion_r2792980264
########## AGENTS.md: ########## @@ -0,0 +1,262 @@ +<!-- +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. +--> +# AGENTS.md + +This file summarizes key development rules for AI/IDE assistants and contributors working on Apache TinkerPop™. The +canonical sources for project policy and technical details are: + +- `README.md` +- `CONTRIBUTING.md` +- Developer documentation at `docs/src/dev/**` and on the website + +This file must not contradict those documents. If it appears to, treat them as canonical and update this file +accordingly. + +*** + +## 1. Project overview + +Apache TinkerPop is a graph computing framework that provides: + +- The Gremlin traversal language +- A common interface across many graph systems (OLTP and OLAP) +- A reference in‑memory graph (TinkerGraph), Gremlin Server, and language variants + +Key external docs (for hints, not to scrape blindly): + +- Project website: https://tinkerpop.apache.org +- Reference docs: https://tinkerpop.apache.org/docs/current/reference/ +- Recipes: https://tinkerpop.apache.org/docs/current/recipes/ +- Developer docs: https://tinkerpop.apache.org/docs/current/dev/developer/ +- Upgrade docs: https://tinkerpop.apache.org/docs/current/upgrade/ +- IO Documentation: https://tinkerpop.apache.org/docs/current/dev/io +- Provider documentation and Gremlin Semantics: https://tinkerpop.apache.org/docs/current/dev/provider + +*** + +## 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.) +- Developer docs: `docs/src/dev/developer/**` +- Future plans: `docs/src/dev/future/**` +- 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. Build and test recipes + +These commands are the **preferred** way for agents and contributors to build and test. + +### 3.1 Basic build and test + +- Build everything: + + ```bash + mvn clean install + ``` + +- Build a specific module: + + ```bash + mvn clean install -pl <module-name> + ``` + + Example: + + ```bash + mvn clean install -pl tinkergraph-gremlin + ``` + +### 3.2 Integration and specialized builds + +- Enable integration tests: + + ```bash + mvn clean install -DskipIntegrationTests=false + ``` + +- Include Neo4j tests: + + ```bash + mvn clean install -DincludeNeo4j + ``` + +- Build using Docker: + + ```bash + docker/build.sh -t -i -n + ``` + +### 3.3 Language variant (GLV) builds + +- Python: + + ```bash + mvn clean install -Pglv-python + ``` + +- .NET: + + ```bash + mvn clean install -Pgremlin-dotnet + ``` + +- JavaScript: + + ```bash + mvn clean install -pl gremlin-javascript + ``` + +- Go: + + ```bash + mvn clean install -pl gremlin-go + ``` + +*** + +## 4. Documentation and site + +TinkerPop’s documentation is AsciiDoc‑based and lives under `docs/src/**`. + +### 4.1 Local docs build + +- Generate documentation: + + ```bash + bin/process-docs.sh Review Comment: deleted that. another section i didn't focus to heavily on and my tools never ever tried to use any of that. not even sure we're at a stage with these tools where we would use that. removed the section. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
