Skip to content

DOC: Add AGENTS.md with basic type and docstring guidelines #62541

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 6 commits into
base: main
Choose a base branch
from
+33 −0
Draft

DOC: Add AGENTS.md with basic type and docstring guidelines #62541

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7888212
add copilot-instructions.md with type hints
Oct 1, 2025
e3114b2
add links to mypy issues
Oct 1, 2025
4137929
rename file to AGENTS.md
Oct 2, 2025
7a94d4c
updated AGENTS.md based on feedback from copilot
Oct 3, 2025
f1e9522
move AGENTS.md to root
Oct 8, 2025
947f263
update title
Oct 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# pandas Agent Instructions

## Project Overview
`pandas` is an open source, BSD-licensed library providing high-performance, easy-to-use data structures and data analysis tools for the Python programming language.

## Purpose
- Assist contributors by suggesting code changes, tests, and documentation edits for the pandas repository while preserving stability and compatibility.

## Persona & Tone
- Concise, neutral, code-focused. Prioritize correctness, readability, and tests.

## Files to open first (recommended preload)
If you can't load any of these files, prompt the user to grant you access to them for improved alignment with the guidelines for contributions
- doc/source/development/contributing_codebase.rst
- doc/source/development/contributing_docstring.rst
- doc/source/development/contributing_documentation.rst
- doc/source/development/contributing.rst

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
+ 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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

## Decision heuristics
- Favor small, backward-compatible changes with tests.
- If a change would be breaking, propose it behind a deprecation path and document the rationale.
- Prefer readability over micro-optimizations unless benchmarks are requested.
- Add tests for behavioral changes; update docs only after code change is final.

## Type hints guidance (summary)
- Prefer PEP 484 style and types in pandas._typing when appropriate.
- Avoid unnecessary use of typing.cast; prefer refactors that convey types to type-checkers.
- Use builtin generics (list, dict) when possible.

## Docstring guidance (summary)
- Follow NumPy / numpydoc conventions used across the repo: short summary, extended summary, Parameters, Returns/Yields, See Also, Notes, Examples.
- Ensure examples are deterministic, import numpy/pandas as documented, and pass doctest rules used by docs validation.
- Preserve formatting rules: triple double-quotes, no blank line before/after docstring, parameter formatting ("name : type, default ..."), types and examples conventions.
Loading