The Open Framework for Building Agents
Clarify contributor issue policy (#2348)
Colton Paddenaf28c8d13a57
diff --git a/.agents/skills/gh-pr-description/SKILL.md b/.agents/skills/gh-pr-description/SKILL.mdindex a4d1738a6..d40502274 100644--- a/.agents/skills/gh-pr-description/SKILL.md+++ b/.agents/skills/gh-pr-description/SKILL.md@@ -18,7 +18,8 @@ Fill in the repository template. Write for a reviewer:- summarize meaningful behavior and decisions, not files or commits- mention breaking changes, preserved behavior, scope boundaries, or stackedPRs only when relevant-- link the prior issue with `Closes #N`, `Related to #N`, or equivalent+- link a prior issue or discussion with `Closes #N`, `Related to #N`, or+ equivalent when one exists; never create an issue solely for the PR- scale length with risk, not diff sizeAppend a `### Diff size` section after the template checklist. This must be thediff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlindex 9fc5f58ee..962f65e2a 100644--- a/.github/ISSUE_TEMPLATE/bug_report.yml+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -97,6 +97,21 @@ body:...validations:required: true+ - type: textarea+ id: implementation-prompt+ attributes:+ label: Suggested implementation prompt+ description: Optionally provide a prompt a maintainer or coding agent could use to fix this bug after it is accepted. Include the expected behavior, constraints, and acceptance criteria rather than prescribing unnecessary implementation details.+ placeholder: |+ Fix ...++ Requirements:+ - ...++ Acceptance criteria:+ - ...+ validations:+ required: false- type: textareaid: contextattributes:diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlindex 2a9bed661..0dc26034e 100644--- a/.github/ISSUE_TEMPLATE/feature_request.yml+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -16,6 +16,21 @@ body:description: What would you like to see? Include API sketches or examples if you have them.validations:required: true+ - type: textarea+ id: implementation-prompt+ attributes:+ label: Suggested implementation prompt+ description: Optionally provide a prompt a maintainer or coding agent could use to implement this proposal after it is accepted. Include the intended behavior, constraints, and acceptance criteria rather than prescribing unnecessary implementation details.+ placeholder: |+ Implement ...++ Requirements:+ - ...++ Acceptance criteria:+ - ...+ validations:+ required: false- type: textareaid: alternativesattributes:diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex 322581fbc..995f621bc 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -1,10 +1,11 @@### Summary<!---Link the issue where this change was discussed (for example, "Closes #123" or-"Related to #123"). Explain the concrete problem and solution, then summarize-meaningful behavior or decisions—not changed files or commits. Call out breaking-changes, preserved behavior, scope boundaries, or stacked PRs when relevant.+If an issue or discussion already exists, link it (for example, "Closes #123"+or "Related to #123"). Do not create an issue solely to accompany this pull+request. Explain the concrete problem and solution, then summarize meaningful+behavior or decisions—not changed files or commits. Call out breaking changes,+preserved behavior, scope boundaries, or stacked PRs when relevant.-->### Validation@@ -16,7 +17,7 @@ results or limitations. Explain when tests are not applicable.### Checklist-- [ ] I linked an issue with prior discussion confirming this change is wanted+- [ ] This change was requested or approved by a maintainer- [ ] I ran the relevant checks from `CONTRIBUTING.md`- [ ] I added tests and documentation where relevant- [ ] I added a changeset if this touches the published `eve` packagediff --git a/AGENTS.md b/AGENTS.mdindex 4ca513f4c..d0352e10f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -33,8 +33,9 @@ before pushing.PR descriptions are reviewer-oriented explanations of the problem, solution,meaningful behavior changes, and validation—not file lists or commit logs. Keep-them proportional to the change, link the prior issue, call out important scope-boundaries or preserved behavior, and report only checks actually run. Use the+them proportional to the change, link a prior issue or discussion when one+exists, call out important scope boundaries or preserved behavior, and report+only checks actually run. Never create an issue solely to accompany a PR. Use the[`gh-pr-description`](./.agents/skills/gh-pr-description/SKILL.md) skill whendrafting or updating one.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 6c8156cbb..a9e5f60c7 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -165,49 +165,52 @@ Also add the extension identity to [`packages/eve-catalog/src/index.ts`](./packaUser-facing docs live in [`docs/`](./docs) and are published with the `eve` npm package and rendered by the docs site in [`apps/docs`](./apps/docs). If your change alters public behavior, update the relevant doc in the same PR and run `pnpm docs:check`.-## Before opening a pull request+## Proposing a change-Every pull request must be tied to an issue. Before opening a PR, search the-existing issues, discussions, and pull requests so you do not duplicate active-work. If there is no existing issue, open one with the relevant template and-describe the problem, use case, or bug reproduction.+If you are an external contributor and have not been invited to implement a+change, open an issue instead of a pull request. Search the existing issues,+discussions, and pull requests first so you do not duplicate active work. Use+the relevant issue template to describe the problem, use case, or bug+reproduction. You may also include a suggested implementation prompt that a+maintainer or coding agent could use after the proposal is accepted.For changes to public APIs, agent behavior, compiler/runtime internals,dependencies, generated artifacts, fixture contracts, or any non-trivial-implementation detail, wait for discussion on the issue before investing in the+implementation detail, wait for maintainer agreement before investing in animplementation. The goal is to agree that the problem is real and that the-proposed direction fits eve before review shifts to code. Bug fixes should link-to an issue with a reproduction or failing test case so the problem remains-tracked even if a specific fix is not accepted.+proposed direction fits eve before review shifts to code.-To avoid PRs that are unlikely to be reviewed or merged:+To make a proposal easier to evaluate:-- Do not send broad rewrites, style-only churn, formatting-only changes, or+- Do not propose broad rewrites, style-only churn, formatting-only changes, orgenerated-output refreshes unless a maintainer asked for them.-- Do not bundle unrelated fixes or refactors into one PR. Split them so each PR- has one reviewable purpose.-- Do not add runtime dependencies without prior agreement. Prefer eve-owned+- Keep each issue focused on one problem.+- Do not propose runtime dependencies without a concrete need. Prefer eve-ownedwrappers, vendored code, or generated artifacts, and remember that the `eve`package should keep runtime dependencies minimal.-- Do not change public behavior based only on a hypothetical use case. Include a- concrete user story, reproduction, fixture, or test that shows the need.-- Do not claim an issue silently. Comment before starting work, and check the- thread first in case someone else is already working on it.+- Do not propose public behavior based only on a hypothetical use case. Include+ a concrete user story or, for bugs, a reproduction.+- Do not claim an issue silently. Wait for a maintainer to invite an+ implementation, and check the thread first in case someone else is already+ working on it.## Submitting a pull request+Team members and contributors explicitly invited to implement a change may+open a pull request. Link the issue or discussion where the change was agreed+on when one exists. Do not create an issue solely to accompany a pull request.+1. Fork the repo and create a branch from `main`.-2. Link the issue where the change was discussed and agreed on.-3. Make your change, including tests and docs where relevant.-4. Sign off every commit with `git commit -s`.-5. If the change affects the published `eve` package, add a changeset:+2. Make your change, including tests and docs where relevant.+3. Sign off every commit with `git commit -s`.+4. If the change affects the published `eve` package, add a changeset:```bashpnpm changeset```-6. Make sure `pnpm lint`, `pnpm typecheck`, and `pnpm test` pass.-7. Open the PR with a clear description of the problem and solution.+5. Make sure `pnpm lint`, `pnpm typecheck`, and `pnpm test` pass.+6. Open the PR with a clear description of the problem and solution.Releases are managed with [Changesets](https://github.com/changesets/changesets) by the maintainers.