Add a simple AGENTS.md file #16124
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| # typeshed - Python type stub repository | ||
|
|
||
| typeshed contains [type stubs](https://typing.python.org/en/latest/spec/distributing.html) | ||
| for Python's standard library as well as for some packages available on | ||
| [PyPI](https://pypi.org/) (usually called "third-party stubs" in typeshed) | ||
| that don't provide their own type annotations. | ||
|
|
||
| The standard library stubs get vendored by type checkers. Each third-party | ||
| stub package is distributed as a separate package (usually called | ||
| `types-<name>`) on PyPI. | ||
|
|
||
| ## Directory Structure | ||
|
|
||
| - `stdlib/` - Python standard library stubs | ||
| - `stubs/` - PyPI package stubs, one directory per package | ||
| - `scripts`/ - utility scripts | ||
| - `tests/` - scripts for various tests, see `tests/README.md` | ||
| - `lib/` - utility modules used by multiple scripts | ||
|
|
||
| ## Running tests | ||
|
|
||
| To run all tests, run: | ||
|
|
||
| ```bash | ||
| python3 -m venv .venv | ||
| source .venv/bin/activate | ||
| pip install -U pip | ||
| pip install -r requirements-tests.txt | ||
| python tests/runtests.py <path> | ||
| ``` | ||
|
|
||
| `<path>` is either: | ||
|
|
||
| - `stdlib/<stub>.pyi` | ||
| - `stubs/<package>` | ||
|
|
||
| See `tests/README.md` for more information about running tests. | ||
|
|
||
| ## Pull Requests | ||
|
|
||
| When opening pull requests, do the following: | ||
|
|
||
| - Follow the guidance from `CONTRIBUTING.md`. | ||
| - Run the tests as described above before submitting. | ||
| - Don't include tests for .pyi files, unless the situation is complex. See | ||
| `tests/REGRESSION.md`. | ||
|
Collaborator
There was a problem hiding this comment. In this file, "See some_file" is prone to get outdated if documentation is refactored. Maybe it's better to leave them out? In my (somewhat little) experience, agents are quite good at finding the thing they are looking for.
Collaborator
Author
There was a problem hiding this comment. I'm not too concerned about that. The structure hasn't changed that much, and personally I always run a simple search when renaming or moving files to find all occurrences. And I've seen agents miss other instruction files unless given concrete instructions to read them. |
||
| - Use a concise PR description: | ||
| - Either link to an issue or describe the problem briefly, never both. | ||
| - Limit the summary of changes to one sentence, unless the PR is complex. | ||
| - Don't include a testing plan. | ||
| - Add the name of the agent used to the PR description. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This won't work on Windows, and also linux distros that only ship a
pythonexecutable.I don't know whether these commands are more automagical than what users expect their agents to do. For example, what happens if a user has already created a venv with a different name? Will the agent blindly create another one? Maybe someone who uses agents more than I do can comment on that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe it's better to just describe what to do ("create a venv", "install requirements using ...", "run runtests") The agents should be able to figure out the correct command for their environment.