Updating contribution guidelines (#5006)

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
Co-authored-by: Douwe Maan <[email protected]>

.github/pull_request_template.md

@@ -1,25 +1,15 @@
 <!-- Thank you for contributing to Pydantic AI! -->
 
-<!-- Please add the issue number that should be closed when this PR is merged. -->
-<!-- If there is no issue, please create one first, even for simple bug fixes. -->
+<!-- Please read the contributing guide: https://ai.pydantic.dev/contributing/ -->
+
+<!-- For non-trivial changes, link an issue that a maintainer has agreed on -->
+<!-- and assigned to you. Unassigned PRs may be auto-closed. -->
+<!-- Trivial fixes (typos, broken links, small doc improvements) don't need an issue. -->
 
 - Closes #<issue>
 
-### Pre-Review Checklist
-
-<!-- These checks need to be completed before a PR is reviewed, -->
-<!-- but you can submit a draft early to indicate that the issue is being worked on. -->
+### Checklist
 
 - [ ] Any **AI generated code** has been reviewed line-by-line by the human PR author, who stands by it.
 - [ ] No **breaking changes** in accordance with the [version policy](https://github.com/pydantic/pydantic-ai/blob/main/docs/version-policy.md).
-- [ ] **Linting and type checking** pass per `make format` and `make typecheck`.
 - [ ] **PR title** is fit for the [release changelog](https://github.com/pydantic/pydantic-ai/releases).
-
-### Pre-Merge Checklist
-
-<!-- These checks need to be completed before a PR is merged, -->
-<!-- but as PRs often change significantly during review, -->
-<!-- it's OK for them to be incomplete when review is first requested. -->
-
-- [ ] New **tests** for any fix or new behavior, maintaining 100% coverage.
-- [ ] Updated **documentation** for new features and behaviors, including docstrings for API docs.

CONTRIBUTING.md

@@ -0,0 +1 @@
+docs/contributing.md

docs/contributing.md

@@ -1,5 +1,90 @@
 We'd love you to contribute to Pydantic AI!
 
+## How we work — the short version
+
+Pydantic AI is maintained by a small team. We set our own priorities based on what benefits the most users, and we work through issues and PRs in that order — not in the order they arrive.
+
+- **Found a bug?** Open an issue with a clear description and a minimal reproducible example. Including a [Logfire](https://logfire.pydantic.dev/) trace link helps us debug dramatically faster.
+- **Want a feature or API change?** Open an issue describing the problem you're solving. Do not start with code.
+- **Want to help build a feature?** Comment on the issue explaining why you need it and what context you bring. We call this being a "champion" — more on that below.
+- **Have a fix or code to share?** Make sure a maintainer has agreed to the approach on the issue and assigned you. Then open a PR.
+
+The rest of this page explains why we work this way and what to expect.
+
+## Before you write code
+
+For anything non-trivial, align with a maintainer on the approach before writing code. A pre-aligned PR is much faster to land than one we're seeing cold.
+
+### Trivial fixes
+
+Typos, broken links, small doc improvements, obvious one-line fixes: just open a PR. No issue needed.
+
+### Bug fixes
+
+If the fix could reasonably go more than one way, or you're unsure it's actually a bug: open an issue first. Include a minimal reproducible example and ideally a [Logfire trace link](https://logfire.pydantic.dev/) showing the problem. For well-scoped bugs, we may generate a fix internally — the most valuable thing you can do is file a clear report and then validate that the fix works for your use case.
+
+### Features, integrations, or API changes
+
+Before writing code, ask whether the change needs to live in core at all. Many additions work better as a [capability](capabilities.md) — a self-contained extension you publish as your own package and use immediately without waiting on us. Capabilities are the primary extension point for Pydantic AI. Once yours has real users and a stable shape, come back and we can talk about upstreaming.
+
+If it does belong in core:
+
+1. **Search first.** If an existing issue covers your need, comment there. If the closest match is only related, open a new issue and link it.
+2. **Describe the problem, not just the solution.** Tell us what you're building, what's blocking you, and what you've tried. This context matters more than code.
+3. **Propose a plan before building.** Post the shape of the solution on the issue, or open a draft PR with just a `PLAN.md`. For larger features, we do short video calls with contributors to iterate on the design — a 20-minute call often saves weeks of async review cycles.
+4. **Wait for assignment.** A maintainer needs to agree on the approach and assign the issue to you before you open a PR. Unassigned PRs may be auto-closed.
+
+!!! warning
+    Writing a large feature PR without prior alignment is the most common way for a contribution to stall or be closed.
+
+## Champions
+
+A "champion" is someone who needs a feature, has context on the problem, and is willing to invest time to help us get it right. If you want to champion a feature:
+
+- Comment on the issue explaining: what you're building, why you need this, and what you can contribute (domain knowledge, testing, validation).
+- We prioritize features where one or more champions with production use cases have stepped up. A feature with no champion stays in the backlog until either we prioritize it ourselves or someone with real context shows up.
+- Being a champion doesn't mean writing the code. It means shaping the plan and validating the result. For significant features, we'll set up a call to iterate on the design together.
+
+Champions are credited as co-authors when the feature ships.
+
+## What to expect during review
+
+### We review PRs in our priority order, not submission order
+
+We do not automatically triage every new PR. PRs on issues we have not pre-aligned on are not in our review queue, regardless of how well written they are. If no maintainer has agreed to the change on an issue and assigned it to you, assume we have not seen your PR.
+
+Even for PRs with code we've previously engaged with: we treat all contributed code as a starting point, not a finished product. We review and prioritize PRs based on the feature's importance to the project, not on how much effort went into the code. This is a change from how open source traditionally worked, and we'd rather be honest about it than leave PRs sitting with no signal.
+
+**If you want to know where your PR stands**, the best thing to do is ping `#pydantic-ai` on [Pydantic Slack](https://logfire.pydantic.dev/docs/join-slack/).
+
+### We may rewrite or supersede your code
+
+We treat contributed code as illustrative: a starting point that shows the shape of the change and proves the approach works, not the final form we merge. The most useful thing you can give us for a non-trivial change is a plan plus a working example — not a polished, merge-ready implementation.
+
+On any PR, we may push commits to your branch, open a follow-up PR that supersedes yours, or rewrite from scratch. For security reasons, we lean toward rewriting contributed code rather than merging as-is. You will still be credited as the original author.
+
+Please don't spend effort chasing green CI, addressing every automated review comment, or rebasing for merge conflicts on a PR we haven't pre-aligned on. If we take the change forward, that polish gets thrown away when we rewrite. Get the approach working, then stop and ping us on Slack.
+
+### Automated review is advisory, not a gate
+
+PRs are automatically reviewed by Devin and our own tooling. These reviews are advisory:
+
+- A bot approval does not mean your PR is ready to merge. Only a human maintainer's review counts.
+- A bot finding does not mean you must act on it. If you disagree, say so.
+- If automated review is generating noise on your PR, tell us. We use that feedback to retune the tooling.
+
+### Priority
+
+We receive far more contributions than we can review, and we focus where it has the most impact. We cannot promise to get to every PR, even good ones, and we'd rather say so up front than leave your work open indefinitely with no signal.
+
+Features that align with our roadmap and have active champions get priority. Features that could live as a [capability](capabilities.md) or workaround in user code: shipping it yourself is often the fastest path. Once it has traction, come back and we can talk about upstreaming.
+
+## If your PR or issue has gone quiet
+
+1. Ping `#pydantic-ai` on [Pydantic Slack](https://logfire.pydantic.dev/docs/join-slack/) with a link.
+2. Say what you need: "Can you take a look?", "I'm blocked — is this on your radar?", or "Should I close this?" are all fine.
+3. If you've been waiting weeks without any human response, flag it. That's a process failure on our side and we want to know.
+
 ## Installation and Setup
 
 Clone your fork and cd into the repo directory