This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch agents in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit f446bd5feb3e503850d3e4e2d7c0c452f467be48 Author: Stephen Mallette <[email protected]> AuthorDate: Tue Feb 10 09:17:41 2026 -0500 Added AGENTS.md This is just an initial attempt at making the repository a bit more friendly to AI agents/tools. Moves README/CONTRIBUTING to markdown which is more standard that asciidoc for these things. Expanded the content of both of those files. AGENTS.md is meant to be generic to any AI agent/tool as TinkerPop isn't prescriptive in that regard. With AGENTS.md we at least have a centralized place for any tool to learn how to contribute here. --- AGENTS.md | 262 ++++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.asciidoc | 8 +- CONTRIBUTING.md | 113 ++++++++++++++++++++++ README.asciidoc | 2 +- README.md | 150 +++++++++++++++++++++++++++++ 5 files changed, 527 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..fd0d039dcf --- /dev/null +++ b/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 + ``` + +- Generate the website: + + ```bash + bin/generate-home.sh + ``` + +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. + +*** + +## 5. Coding and testing conventions + +Agents should follow these conventions when generating or editing code and tests. + +### 5.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 + +- 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: + + ```text + gremlin-tests/src/main/resources/org/apache/tinkerpop/gremlin/test/features + ``` + +### 5.3 Deprecation + +When deprecating code: + +1. Add the `@Deprecated` annotation. +2. Add Javadoc with: + - `@deprecated As of release x.y.z, replaced by {@link SomeOtherClass#someNewMethod()}` + - `@see <a href="https://issues.apache.org/jira/browse/TINKERPOP-XXX";>TINKERPOP-XXX</a>` +3. Keep deprecated methods under test. +4. Create or update the associated JIRA issue to track eventual removal. +5. Update upgrade documentation and, when appropriate, `CHANGELOG.asciidoc`. + +Agents must **not** remove deprecated APIs or change public signatures without an explicit instruction or associated +issue. + +*** + +## 6. Changelog, license, and checks + +When changes affect behavior, APIs, or user‑visible features: + +- 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. + +*** + +## 7. Do and don’t for agents + +These rules apply to any AI/IDE assistant operating on this repository. + +### 7.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. + +### 7.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. + +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. + +*** + +## 8. 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. \ No newline at end of file diff --git a/CONTRIBUTING.asciidoc b/CONTRIBUTING.asciidoc index 4711689c04..2e29f11ce6 100644 --- a/CONTRIBUTING.asciidoc +++ b/CONTRIBUTING.asciidoc @@ -16,10 +16,4 @@ limitations under the License. //// == Contributing to Apache TinkerPop -Contributions via GitHub pull requests are gladly accepted from their original -author. By submitting any copyrighted material via pull request, email, or other means -you agree to license the material under the project's open source license and -warrant that you have the legal authority to do so. - -Please see the "Developer Documentation" for more information on -link:http://tinkerpop.apache.org/docs/current/dev/developer/#_contributing[contributing] to TinkerPop. +This file is here for historical reasons only. See CONTRIBUTING.md to learn how to contribute. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..3b26e27dec --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,113 @@ +<!-- +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. +--> +# Contributing to Apache TinkerPop + +Thank you for your interest in contributing to Apache TinkerPop™! Contributions of code, tests, documentation, examples, +and ideas are all welcome. + +Contributions via GitHub pull requests are gladly accepted from their original author. By submitting any copyrighted +material via pull request, email, or other means, you agree to license the material under the project's open source +license and warrant that you have the legal authority to do so. + +Please see the "Developer Documentation" for more information on +[contributing](http://tinkerpop.apache.org/docs/current/dev/developer/#_contributing) to TinkerPop. + +## Ways to contribute + +You can help TinkerPop in many ways, including: [tinkerpop.apache](https://tinkerpop.apache.org/docs/current/dev/developer/) + +- Reporting bugs and proposing improvements. +- Contributing code changes and tests. +- Writing and improving documentation and examples. +- Helping users on mailing lists, issue trackers, and forums. +- Sharing recipes, tutorials, and best practices. + +If you are new to the project, unresolved issues marked as “trivial” in [JIRA](https://issues.apache.org/jira/browse/TINKERPOP) +are a good place to start. + +## Getting started + +. Fork the [Apache TinkerPop repository](https://github.com/apache/tinkerpop) on GitHub and clone your fork locally. +. Set up a development environment following the [Developer Documentation](https://tinkerpop.apache.org/docs/current/dev/developer/) +. For non‑trivial work, tie your changes to an existing JIRA issue or create a new one if needed. + +## Contribution process + +The general workflow for code or documentation changes is: [tinkerpop.apache](https://tinkerpop.apache.org/docs/current/dev/developer/) + +1. **Discuss (recommended)** + - For larger or potentially breaking changes, start a discussion on the TinkerPop dev mailing list and/or in JIRA. + +2. **Implement** + - Make your changes in a feature branch in your fork. + - Include tests for code changes whenever possible. + - Update documentation, recipes, and upgrade notes when behavior or APIs change. + +3. **Build and test** + - Run the relevant Maven builds and tests as described in the Developer Documentation (for example, `mvn clean install`). + - For significant contributions, consider running the broader test and documentation build described in the development‑environment guide. + +4. **Prepare your pull request** + - Reference the associated JIRA issue in your commit message/pull request description. + - Keep pull requests focused and reasonably small where possible. + - Update `CHANGELOG.asciidoc` and the upgrade documentation if your change affects user‑visible behavior or public API. + +5. **Submit and respond to review** + - Open a GitHub pull request against the appropriate branch. + - Automated builds and tests will run via [GitHub Actions](https://github.com/apache/tinkerpop/actions); please address any failures. + - Committers and other contributors may request changes; you can add more commits to the same branch to update the pull request. + - Please be patient; we will do our best to move your contribution forward. + +## Documentation contributions + +TinkerPop documentation is maintained primarily as AsciiDoc under `docs/src/**` and published per release. + +When changing documentation: + +- Edit the appropriate AsciiDoc files in `docs/src/`. +- Use the existing structure (books and index files) and update `index.asciidoc` entries so new content is included. +- For project documentation, submit changes via pull request, just like code. + +The Developer Documentation includes detailed information on how to build and preview the documentation locally. + +The TinkerPop website is also maintained in the repository under `docs/site` as HTML files. Contributions to that are +also welcome via pull request. + +## Using AI and IDE assistants + +If you use AI coding agents or IDE assistants when working on TinkerPop, please also consult `AGENTS.md`. That file +summarizes: + +- Recommended build and test commands. +- Coding and testing conventions. +- “Do and don’t” guidance specific to automated tools. + +Please consider [ASF Generative Tooling Guidance](https://www.apache.org/legal/generative-tooling.html) when making +contributions with these tools. + +## Community and communication + +TinkerPop is an Apache Software Foundation project and follows [ASF community guidelines](https://community.apache.org/contributors/). + +For more detail on: + +- [Mailing lists](https://lists.apache.org/[email protected]) and project communication. +- Roles and responsibilities (contributors, committers, PMC). +- Release and voting processes. + +please see the Developer Documentation’s contributing and governance sections: +https://tinkerpop.apache.org/docs/current/dev/developer/ \ No newline at end of file diff --git a/README.asciidoc b/README.asciidoc index 5f1219a214..7d588a11bd 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -14,7 +14,7 @@ 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. //// -== TinkerPop3 +== Apache TinkerPop image:https://img.shields.io/maven-central/v/org.apache.tinkerpop/gremlin-driver?color=brightgreen[link="https://mvnrepository.com/artifact/org.apache.tinkerpop/gremlin-driver";] image:https://img.shields.io/nuget/v/Gremlin.Net?color=brightgreen[link="https://www.nuget.org/packages/Gremlin.Net";] image:https://img.shields.io/pypi/v/gremlinpython?color=brightgreen[link="https://pypi.org/project/gremlinpython/";] diff --git a/README.md b/README.md new file mode 100644 index 0000000000..5c9e4dadb5 --- /dev/null +++ b/README.md @@ -0,0 +1,150 @@ +<!-- +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. +--> +# Apache TinkerPop + +[](https://mvnrepository.com/artifact/org.apache.tinkerpop/gremlin-driver) +[](https://www.nuget.org/packages/Gremlin.Net) +[](https://pypi.org/project/gremlinpython/) +[](https://www.npmjs.com/package/gremlin) +[](https://pkg.go.dev/github.com/apache/tinkerpop/gremlin-go/v3) + +[](https://codecov.io/gh/apache/tinkerpop) + +[](https://tinkerpop.apache.org) + +Apache TinkerPop™ is a graph computing framework for both graph databases (OLTP) and graph analytic systems (OLAP). It +provides the Gremlin graph traversal language, drivers, and tools for working with property graphs across a wide variety +of underlying data systems. + +## Project overview + +TinkerPop defines a common interface and language (Gremlin) so that applications can work against many different graph +systems without being locked into a single vendor. It includes a reference in‑memory graph database (TinkerGraph), +Gremlin Server, language variants, and a rich collection of recipes and documentation. + +Key resources: + +- Website: https://tinkerpop.apache.org +- Documentation Index: https://tinkerpop.apache.org/docs/current/index.html +- Upgrade documentation: https://tinkerpop.apache.org/docs/current/upgrade/ +- Reference documentation: https://tinkerpop.apache.org/docs/current/reference/ +- Recipes: https://tinkerpop.apache.org/docs/current/recipes/ +- Provider documentation and Gremlin Semantics: https://tinkerpop.apache.org/docs/current/dev/provider +- Developer documentation: https://tinkerpop.apache.org/docs/current/dev/developer +- IO Documentation: https://tinkerpop.apache.org/docs/current/dev/io +- Roadmap and proposals: https://tinkerpop.apache.org/docs/current/dev/future/ +- Javadocs: https://tinkerpop.apache.org/javadocs/current/full/, [core javadoc](https://tinkerpop.apache.org/javadocs/current/core/) + +## Building and Testing + +TinkerPop uses [Maven](https://maven.apache.org/) and requires Java 11/17 for proper building and proper operations. To +build, execute unit tests and package Gremlin Console/Server run: + +```bash +mvn clean install +``` + +Please see the [Building on Windows](docs/src/dev/developer/development-environment.asciidoc#building-on-windows) +section for Windows-specific build instructions. + +The zip distributions can be found in the following directories: + +1. `gremlin-server/target` +2. `gremlin-console/target` + +Please see the CONTRIBUTING.md file for more detailed information and options for building, test running and developing +TinkerPop. + +## Get Started + +Download [Gremlin Console](https://tinkerpop.apache.org/download.html) (compatible with Java 11/17) and unzip to a +directory, then: + +```bash +$ bin/gremlin.sh + + \,,,/ + (o o) +-----oOOo-(3)-oOOo----- +plugin activated: tinkerpop.server +plugin activated: tinkerpop.utilities +plugin activated: tinkerpop.tinkergraph +gremlin> Gremlin.version() +==>3.8.0 +gremlin> graph = TinkerFactory.createModern() +==>tinkergraph[vertices:6 edges:6] +gremlin> g = traversal().with(graph) +==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard] +gremlin> g.V().has('name','vadas').valueMap() +==>[name:[vadas], age:[27]] +``` + +From the Gremlin Console, you can connect to a TinkerGraph instance and run your first traversals. Refer to the +[Getting Started](https://tinkerpop.apache.org/docs/current/tutorials/getting-started/) for detailed walkthroughs and +examples. + +## Using TinkerPop + +Common ways to use TinkerPop include: + +- Embedding **TinkerGraph** in your application for development, testing, or lightweight graph workloads. +- Connecting to a **Gremlin‑enabled graph database** via drivers or [Gremlin Server](https://tinkerpop.apache.org/docs/current/reference/#gremlin-server). +- Running **Gremlin traversals** from the JVM, or via Gremlin Language Variants (Python, .NET, JavaScript, Go, etc.). +- Using the **Gremlin Console** for interactive exploration, debugging, and learning. + +See the [Reference Documentation](https://tinkerpop.apache.org/docs/current/reference/) for supported features, +configuration options, and other details. + +## Documentation + +The full TinkerPop documentation is published on the project website and is also maintained in this repository under +`docs/src/` as AsciiDoc “books.” + +When changing or adding documentation, follow the existing AsciiDoc structure in `docs/src/**` and update the +relevant `index.asciidoc` files so new content is included in the build. + +## Contributing + +Contributions to Apache TinkerPop are welcome. The [Developer Documentation](https://tinkerpop.apache.org/docs/current/dev/developer) +and contributing guide describe how to set up a development environment, run tests, and submit changes. + +- Contribution guidelines: `CONTRIBUTING.md` in the repository root. +- Developer documentation: https://tinkerpop.apache.org/docs/current/dev/developer/ + +Before opening a pull request, please: + +- Discuss larger changes on the appropriate Apache mailing list. +- Ensure tests pass locally and, where appropriate, add new tests and documentation. +- Update `CHANGELOG.asciidoc` and upgrade docs when behavior or public APIs change. + +## Using AI and IDE assistants + +If you use AI coding agents or IDE assistants when working on TinkerPop, please consult `AGENTS.md`. That file +summarizes: + +- Recommended build and test commands. +- Code style and testing conventions. +- “Do and don’t” guidance specific to automated tools. + +`AGENTS.md` is a concise guide for tools and tool‑using contributors, while `CONTRIBUTING.md` and the +[Developer Documentation](https://tinkerpop.apache.org/docs/current/dev/developer) remain the canonical sources for +project policies and processes. + +## License + +Apache TinkerPop is an open source project of The Apache Software Foundation and is licensed under the Apache License, +Version 2.0. See the `LICENSE` file in this repository for details. \ No newline at end of file
