DOC: Add AGENTS.md with basic type and docstring guidelines #62541
Conversation
|
Thanks for the PR. I don't have any experience with this so am open to experiences from other projects. The github link provides an example of an instructions file that is much more compact than what is provided here: Is there an advantage to this text copied from the guide versus something that would be more bulleted like the example? |
Thanks Will. My goal with the copy-paste was to avoid any controversy over wording. I'll ask copilot to re-write it in a way that is better suited for a copilot-instructions.md and update the PR with what it gives me ;) Separately, on Slack someone made me aware of AGENTS.md which is now natively supported by Github Copilot (among many other agents) so I will update this to be an agents.md instead. |
jzwick
changed the title
There was a problem hiding this comment.
I am neutral to these changes. But I think this file needs to be improved. I think the one from openai/agents.md is a great example.
| - doc/source/development/contributing_docstring.rst | ||
| - doc/source/development/contributing_documentation.rst | ||
| - doc/source/development/contributing.rst | ||
|
|
There was a problem hiding this comment.
| + doc/source/development/contributing_environment.rst | |
It needs instructions on how to build pandas from source. I am not sure if the model will be reliable if it reads all these files. I think it's best to create sections focusing on some aspects and link to the .rst files for additional information. The agents.md highlights:
- Project overview
- Build and test commands
- Code style guidelines
- Testing instructions
- Security considerations
There was a problem hiding this comment.
Thanks for the input. The intent of this PR is to "get the ball rolling" with a simple AGENTS.md, and to continue to expand upon it with subsequent PRs. For the first PR we wanted to stay focused on some simple guidelines around style (types and docstrings), and pointing to the existing contributing_*.rst
I agree that sections with more details for Build, Testing, and Security would be very valuable - we just prefer to have those contributed as separate PRs for more engaged conversation around each of those specifically.
There was a problem hiding this comment.
WRT whether to have the .rst linked at the top, or individually within each of the sections below, I'm open to what others have experience with. In one place seemed more maintainable (e.g. easier to see if one is missing, or renamed, where to update the reference).
|
Is the idea to encourage AI PRs? That’s the opposite of what we want. |
No, we are not trying to encourage AI PRs. IMO the motivation here is acknowledging the reality that many people are already developing with the help of AI agents, so we are trying to improve both the (human) developer's experience and the code quality that ends up in PRs. For example, if we have a good AGENTS.md with robust instructions around the Style Guidelines, then for folks who do leverage copilot, cursor, etc. hopefully that reduces the corrections made at PR review. |
doc/source/whatsnew/vX.X.X.rstfile if fixing a bug or adding a new feature.This PR adds as
AGENTS.mdfile, which is like "a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project." (more on AGENTS.md here)This PR started as a
copilot-instructions.md(see more on copilot-instrucitons.md files here) but the more genericAGENTS.mdwas suggested, which is supported not only by Copilot but also many other AI agents.I have initially populated the file with some simple guidance on Decision Heuristics, Type Hints and Docstrings, based on the existing guidance in the "Contributing" section of the project documentation. The expectation is that the content in this file would grow and become more comprehensive over subsequent PRs.