From 7143d9a06b76d86f48fd46b4400bbb9c3d843a6a Mon Sep 17 00:00:00 2001 From: Darren Date: Mon, 31 Aug 2026 12:51:59 -0400 Subject: [PATCH] docs: add repository agent guide (#888) --- AGENTS.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..01c5ded --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# AGENTS.md + +## Repository purpose + +Papers We Love is a curated directory of academic computer-science papers. +Most changes add or correct entries in topic-level `README.md` files; a smaller +set of papers is hosted in the repository. This is not an application project: +there is no package manager, build, or unit-test suite. + +## Layout + +- The root `README.md` explains the collection and points contributors to the + project policies. +- Each topic directory owns a `README.md` index. Some topics have nested + subtopics; keep an entry with the most specific appropriate topic. +- Hosted papers live beside the topic index. `scripts/download.sh` retrieves + linked PDFs but is not part of a normal documentation-change check. +- `.github/CONTRIBUTING.md` is the source of truth for contribution policy; + `.github/PULL_REQUEST_TEMPLATE.md` lists the information expected in a PR. + +## Editing paper indexes + +- Preserve the target README's existing headings, ordering, Markdown style, + and level of description. Do not reformat unrelated entries. +- Add an academic paper, not a book, blog post, or general reference. Include + a short explanation of its importance when adding a paper, as required by + the contribution guide. +- Include the publication year with a new listing when it is known. +- Prefer a stable, direct source link and verify that the link reaches the + intended paper before submitting it. +- Use `:scroll:` for a repository-hosted paper. A hosted paper must also have + its source URL recorded in that topic's README. +- Respect copyright: only add a paper file when its license permits digital + redistribution. Otherwise, link to the canonical external source instead. +- Name new topic directories in lowercase with underscores; name paper files + in lowercase with dashes and use the full title where practical. + +## Scripts and validation + +- Run `bash -n scripts/download.sh` after changing the downloader. +- The CI workflow checks Markdown links with Lychee. For edited entries, + manually validate new or changed URLs; run a local Lychee check when it is + available rather than treating a successful Markdown parse as link + validation. +- Inspect `git diff --check` and the focused diff before handoff. Confirm that + each hosted-paper link resolves to the file committed alongside its README. +- Do not run `./scripts/download.sh` as a routine check: it traverses the + collection, downloads network resources, and can create many PDF files. + Use it only when deliberately refreshing a clearly scoped topic. + +## Change hygiene + +- Keep each contribution focused on a paper, topic, link repair, or script + maintenance task. +- Do not modify or remove existing PDFs merely because a downloader finds a + different copy. +- Follow the Code of Conduct and keep PRs ready to squash into one commit, per + the contribution guide.