dcapwell commented on code in PR #4734: URL: https://github.com/apache/cassandra/pull/4734#discussion_r3176608409
########## AGENTS.md: ########## @@ -0,0 +1,74 @@ +# Agent Instructions for Apache Cassandra + +> These instructions apply to all AI-assisted contributions to `apache/cassandra`. + +## Apache Cassandra +Apache Cassandra is a NoSQL distributed database. This is the official Git repository + +## Environment + +- Java 11 (default), 17, 21. +- Python 3 for `cqlsh` and dtests. +- Apache Ant >= 1.10 for all builds. Do NOT attempt to use Maven, Gradle, or any other build tool. Cassandra uses Ant exclusively. +- Do NOT attempt to install dependencies, you do not have Internet access + +## Build + +```bash +.build/sh/ai-build # clean, build JAR, and run checkstyle (output is summarized) +``` + +Do NOT call `ant` directly — always use the `ai-*` wrapper scripts which handle log summarization and correct working directory. + +## Testing + +- Do NOT run the entire test suite. Run only the specific test(s) relevant to your change. + + ```bash + # Run a single unit test class + .build/sh/ai-ci-test org.apache.cassandra.service.StorageServiceServerTest + ``` + +- `ai-ci-test` does NOT support method-level filtering — it runs the entire test class. +- When fixing a bug, first create a regression test that reproduces the failure, then implement the fix and verify. +- Provide test(s) coverage for all new or modified code. + +## Linting and Code Checks + +`.build/sh/ai-build` includes checkstyle validation. There is no need to run checkstyle separately. + +## Code Style +Cassandra enforces style via Checkstyle (run via `.build/sh/ai-build`). The official style guide is at https://cassandra.apache.org/_/development/code_style.html. Always defer to it when in doubt. + +General style conventions: +- 4-space indentation, no tabs. +- Match existing code style in the file you are editing. +- All new files must include the Apache License 2.0 header. +- Concise English documentation is required for complex classes and methods; trivial ones may not require them. + +## Git Workflow +- Do NOT commit unless explicitly asked. +- Commit messages format. For example: Review Comment: > Assuming it can read the JIRA We don't ship that capability yet. I have it in my commit process, its a simple API call that doesn't need auth, but there are tricky bits as the additional authors isn't a standard field, so very easy for agents to get this wrong. Again, I am 100% against asking contributors to *care* about our commit message; this is a committer's issue to me (not every member agrees with my stance btw; its not a settled debate). Also, agent files are for 100% of sessions, and this is needed after all review is done and you are ready to merge; aka its not needed for 100% of sessions so can cause issues. -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
