Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
index 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 stacked
PRs 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 size
Append a `### Diff size` section after the template checklist. This must be the
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 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: textarea
id: context
attributes:
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index 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: textarea
id: alternatives
attributes:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 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` package
diff --git a/AGENTS.md b/AGENTS.md
index 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 when
drafting or updating one.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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`](./packa
User-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 an
implementation. 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, or
generated-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-owned
wrappers, 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:
```bash
pnpm 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.