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 4 commits into
base: main
Choose a base branch
from
Draft

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

Changes from all commits
Commits
Show all changes
4 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
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 .github/AGENTS.md
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

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

Create an AGENTS.md file at the root of the repository. Most coding agents can even scaffold one for you if you ask nicely.

AGENTS.md should go to the project root and not .github/

Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# pandas Agent Instructions (Copilot etc)
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
# pandas Agent Instructions (Copilot etc)
# 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

## 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