Add AGENTS.md file#1336
Conversation
Signed-off-by: Eric Heiden <eric-heiden@outlook.com>
📝 WalkthroughWalkthroughAdds two new documentation files: Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 📜 Recent review detailsConfiguration used: Path: .coderabbit.yml Review profile: CHILL Plan: Pro 📒 Files selected for processing (2)
✅ Files skipped from review due to trivial changes (1)
🚧 Files skipped from review as they are similar to previous changes (1)
⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds an AGENTS.md file that provides comprehensive guidelines for AI coding assistants and reviewer agents (such as CodeRabbit) working with the Newton physics engine codebase. The document covers API design principles, naming conventions, and standardized tooling workflows.
Changes:
- Adds
AGENTS.mdwith guidelines on the public API vs internal_srcboundary - Documents naming conventions (prefix-first for classes/methods, kebab-case for CLI args)
- Provides standardized
uvcommands for running examples, tests, pre-commit hooks, and benchmarks
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
AGENTS.md (1)
5-7: Clarify the exception for test code importing from_src.The statement "User code must not import from
newton._src" should clarify that test code is an intentional exception. Based on learnings, tests are allowed to import from_srcinternal modules when needed for testing purposes.📝 Suggested clarification
- **`newton/_src/` is internal library implementation only.** - - User code **must not** import from `newton._src`. + - User code **must not** import from `newton._src` (exception: test code may import from `_src` when needed for testing internal functionality). - Internal refactors can freely reorganize code under `_src` as long as the public API stays stable.Based on learnings from previous code reviews.
📜 Review details
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
AGENTS.md
🧰 Additional context used
🧠 Learnings (8)
📓 Common learnings
Learnt from: preist-nvidia
Repo: newton-physics/newton PR: 701
File: CONTRIBUTING.md:7-7
Timestamp: 2025-09-02T13:59:02.072Z
Learning: The newton-physics/newton-governance repository's CONTRIBUTING.md file contains both "Legal Requirements" (line 73, anchor #legal-requirements) and "Project Members" (line 108, anchor #project-members) sections that can be properly referenced from other repositories' CONTRIBUTING.md files.
Learnt from: shi-eric
Repo: newton-physics/newton PR: 521
File: newton/examples/example_cloth_hanging.py:36-36
Timestamp: 2025-08-12T05:17:34.423Z
Learning: The Newton migration guide (docs/migration.rst) is specifically for documenting how to migrate existing warp.sim functionality to Newton equivalents. New Newton-only features that didn't exist in warp.sim do not need migration documentation.
📚 Learning: 2025-08-12T05:17:34.423Z
Learnt from: shi-eric
Repo: newton-physics/newton PR: 521
File: newton/examples/example_cloth_hanging.py:36-36
Timestamp: 2025-08-12T05:17:34.423Z
Learning: The Newton migration guide (docs/migration.rst) is specifically for documenting how to migrate existing warp.sim functionality to Newton equivalents. New Newton-only features that didn't exist in warp.sim do not need migration documentation.
Applied to files:
AGENTS.md
📚 Learning: 2025-09-02T13:59:02.072Z
Learnt from: preist-nvidia
Repo: newton-physics/newton PR: 701
File: CONTRIBUTING.md:7-7
Timestamp: 2025-09-02T13:59:02.072Z
Learning: The newton-physics/newton-governance repository's CONTRIBUTING.md file contains both "Legal Requirements" (line 73, anchor #legal-requirements) and "Project Members" (line 108, anchor #project-members) sections that can be properly referenced from other repositories' CONTRIBUTING.md files.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-12T17:58:16.929Z
Learnt from: nvlukasz
Repo: newton-physics/newton PR: 519
File: newton/tests/test_ik.py:25-26
Timestamp: 2025-08-12T17:58:16.929Z
Learning: In the Newton physics engine codebase, it's acceptable for tests to import and use private `_src` internal modules and functions when needed for testing purposes, even though this breaks the public API boundary. This is an intentional project decision for test code.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-12T17:51:37.474Z
Learnt from: nvlukasz
Repo: newton-physics/newton PR: 519
File: newton/geometry.py:16-22
Timestamp: 2025-08-12T17:51:37.474Z
Learning: In the Newton public API refactor, common geometry symbols like ParticleFlags and ShapeFlags are now exposed at the top level in newton/__init__.py rather than through newton.geometry. The newton/geometry.py module is intentionally focused only on broad-phase collision detection classes (BroadPhaseAllPairs, BroadPhaseExplicit, BroadPhaseSAP).
Applied to files:
AGENTS.md
📚 Learning: 2025-07-15T21:00:03.709Z
Learnt from: dylanturpin
Repo: newton-physics/newton PR: 394
File: newton/tests/test_ik.py:119-119
Timestamp: 2025-07-15T21:00:03.709Z
Learning: In the Newton physics engine codebase, it's acceptable to test private API functions (those prefixed with underscore) in unit and component tests, as the maintainers consider this appropriate for testing internal functionality.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-27T23:32:48.670Z
Learnt from: shi-eric
Repo: newton-physics/newton PR: 660
File: pyproject.toml:54-59
Timestamp: 2025-08-27T23:32:48.670Z
Learning: In the newton project's pyproject.toml, self-referential extras (e.g., `examples = ["newton[sim]", "newton[importers]", ...]`) are normal and encouraged for dependency management, rather than inlining the dependencies.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-14T17:38:36.106Z
Learnt from: nvlukasz
Repo: newton-physics/newton PR: 519
File: newton/__init__.py:25-29
Timestamp: 2025-08-14T17:38:36.106Z
Learning: The Newton project prefers incremental __all__ building using __all__ += [...] pattern to group exports with their related imports, rather than a single consolidated __all__ at the end of the file.
Applied to files:
AGENTS.md
⏰ Context from checks skipped due to timeout of 900000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Run GPU Tests / Run GPU Unit Tests on AWS EC2
- GitHub Check: Run GPU Benchmarks / Run GPU Benchmarks on AWS EC2
- GitHub Check: run-newton-tests / newton-unittests (windows-latest)
🔇 Additional comments (2)
AGENTS.md (2)
12-22: LGTM! Clear and actionable API design guidelines.The naming conventions and structural principles are well-articulated with concrete examples. The prefix-first naming strategy effectively supports IDE autocomplete and API discoverability.
43-68: No action required. The--extra devand--group devflags are used correctly for their respective purposes:--extra devreferences the optional dependencies group for tests (which includes examples and testing tools), while--group devreferences the dependency-groups specification for ASV benchmarking (which includesasv>=0.6.4). These are two different dependency specifications inpyproject.tomland should use different flags.
|
You might want to add a section how commit messages. You could point to guidelines as a web link like https://github.com/apache/airflow/blob/main/AGENTS.md#pull-request-guidelines |
|
One more request is to have a rule that tells the agents to avoid adding new required dependencies and to strongly prefer not adding new optional dependencies, I would ask an agent to word that in a comprehensible way. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Eric Heiden <eric-heiden@outlook.com>
Signed-off-by: Eric Heiden <eric-heiden@outlook.com>
Signed-off-by: Eric Heiden <eric-heiden@outlook.com>
2378d22
Signed-off-by: Eric Heiden <eric-heiden@outlook.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Eric Heiden <eric-heiden@outlook.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Useful knowledge on API design and code usage for coding LLMs and reviewer agents, such as CodeRabbit.
Also added a CLAUDE.md file that simply imports AGENTS.md because Claude doesn't support it: anthropics/claude-code#6235.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.