[RFC]: Issues and Pull Request Policy Updates

[scottschreckengaust]

Summary

To keep this repository healthy, we enforce automated limits for issues and pull requests.

Motivation

Ideas

Opening many pull requests at once may not give the maintainers bandwidth to service all contributors requests.

• Limit the number of open pull requests per contributor (drafted items don't count against the quota)
• Implement "stale" issues and pull requests (the actions/stale is made for this)
• Preserve long-running work items via a tagged label
• Communicate with comments and actions for the submitter and collaborators on how to keep open
• Potentially enforce a referenced issue with no-issue override to permit minor self-explanatory pull requests to be created without a reference (and for drafts without issues too for exploration)

Detailed Proposal

## Pull request policy

To keep this repository healthy, we enforce automated limits on pull requests:

| Rule                      | Value                        |
|---------------------------|------------------------------|
| Referenced issue          | **open issues referenced**   |
| Max open PRs/user at once | **3**                        |
| Marked stale after        | **7 days** with no activity  |
| Closed after stale        | **3 more days**              |
| Total inactivity window   | **10 days**                  |

### What triggers auto-close

- Opening a PR when ≥ 3 are already open (oldest eligible PRs close first)
- A PR sitting untouched for 10 days of total inactivity
- Lacking a referenced open issue with a GitHub keywords

### How to keep your pull request open

Fix the non-complaint rules and then re-open or alternatively:

- Switch PRs into draft to not count against the maximum quota per user
- Push a commit, add a comment, or request a review to keep activity fresh
- Add the `do-not-close` label for long-running work
- Add the `no-issues` exception label for pull requests that are self-referenced and do not require full issue references 

Alternatives Considered

No response

Drawbacks

Valid small self-contained

Additional Context

No response

[leandrodamascena]

Hey @scottschreckengaust, thanks for putting this together. I agree we need clearer guardrails, and the stale PR automation and referenced issue requirement are great ideas to solve the problem of someone open a PR without a prior issue and not address feedback, for example.

But I'm not sure about the max 3 open PRs per contributor though. The real problem we're seeing is PRs without prior discussion or alignment, not the number of PRs itself. Limiting volume could create false positives when we intentionally break down a larger issue into smaller, focused PRs. Think about a contributor working on a well-scoped issue that naturally splits into 4 or 5 PRs to ease the review. That's exactly the kind of workflow we want to encourage, and a hard cap would get in the way.

IMO this is even more relevant in the age of AI-assisted development. With right prompt and AI-DLC methodology, for example, agents tend to produce smaller, more focused PRs, and that's actually a good pattern. I don't think the volume is the key issue here. I think what matters is whether there was a discussion first, whether the changes are aligned with the project, and whether they meet the quality bar.

I'd rather focus on forcing the workflow of requiring a referenced issue, enforce stale cleanup, and make expectations clearer in CONTRIBUTING.md (PR #217). If contributors follow the process, the number of open PRs shouldn't necessarily matter.

What do you think?

[ConnorKirk]

I think requiring issues for all pull requests is an effective first step, and easy to implement (and roll back). I suggest we do that quickly