Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-9398 Make detailed issues the primary way to contribute to OK (#6389)

Andrew Mikofalvy6d59bd88bb23
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 5eae9a93b..08f23ebf8 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -68,6 +68,13 @@ body:
placeholder: "e.g. 0.16.1"
validations:
required: true
+ - type: textarea
+ id: code-pointers
+ attributes:
+ label: Relevant code
+ description: Files, functions or links to lines you think are involved, with the fix described in words. Please don't paste a full patch. If you want to write the fix yourself, say so here and wait for a maintainer to accept the issue (a `help wanted` label or an explicit go-ahead for a pull request).
+ validations:
+ required: false
- type: textarea
id: logs
attributes:
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index 5215df319..23fd5913d 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -6,7 +6,7 @@ body:
- type: markdown
attributes:
value: |
- Thanks for the suggestion! If this is an open-ended idea worth discussing, [Discord](https://discord.gg/VRKk2EaGHN) is often a better starting place.
+ Thanks for the suggestion! A detailed issue is the main way to contribute to OpenKnowledge: the team builds and reviews the change itself. If this is an open-ended idea worth discussing, [Discord](https://discord.gg/VRKk2EaGHN) is often a better starting place.
- type: textarea
id: problem
attributes:
@@ -20,6 +20,20 @@ body:
label: Proposed solution
validations:
required: false
+ - type: textarea
+ id: done-when
+ attributes:
+ label: What would you see if it worked?
+ description: Describe the behavior that would tell you this is done.
+ validations:
+ required: false
+ - type: textarea
+ id: code-pointers
+ attributes:
+ label: Relevant code
+ description: Files, functions or links to lines you think are involved, with the change described in words. Please don't paste a full patch. If you want to write the change yourself, say so here and wait for a maintainer to accept the issue (a `help wanted` label or an explicit go-ahead for a pull request).
+ validations:
+ required: false
- type: dropdown
id: area
attributes:
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 120156c7c..0e70962ca 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,6 +1,15 @@
+<!--
+Beyond a small fix, a pull request needs an issue a maintainer has accepted, or it may be closed without review.
+The rules are in the "Pull requests" section of CONTRIBUTING.md.
+-->
+
+## Accepted issue
+
+<!-- Paste the full issue URL, e.g. https://github.com/inkeep/open-knowledge/issues/123. Write "small fix" if this is a typo, link, docs or translation correction. -->
+
## What & why
-<!-- One or two sentences on the change and the motivation. Link any related issue. -->
+<!-- One or two sentences on the change and the motivation. -->
## How this was verified
@@ -8,6 +17,8 @@
## Checklist
+- [ ] Linked an accepted issue above, or this is a small fix
+- [ ] I have read and run every line of this change, and can answer questions about it
- [ ] Ran `pnpm check` (lint, typecheck, tests) locally
- [ ] Added a changeset (`pnpm changeset`) if this changes behavior
- [ ] Updated docs if this changes a user-facing surface
@@ -17,7 +28,7 @@
### After you open this PR
-- A maintainer will review your PR. If you don't hear back within a few business days, a comment to nudge is welcome.
+- A maintainer will review your PR if it is a small fix or links an accepted issue. If you don't hear back within a few business days, a comment to nudge is welcome.
- When your change is accepted, this PR closes automatically — that's how it merges, and your authorship is preserved.
See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
diff --git a/.github/scripts/bridge-public-pr-to-monorepo.mjs b/.github/scripts/bridge-public-pr-to-monorepo.mjs
index cc49b80e9..2a3a40f17 100644
--- a/.github/scripts/bridge-public-pr-to-monorepo.mjs
+++ b/.github/scripts/bridge-public-pr-to-monorepo.mjs
@@ -513,7 +513,7 @@ function buildWelcomePublicComment() {
**What happens next:**
-- A maintainer will review your PR.
+- A maintainer will review your PR if it is a small fix (typo, broken link, docs or translation correction) or links an issue a maintainer has accepted. Other pull requests may be closed without review; a detailed issue is the faster path for those.
- If you don't hear back within a few business days, please comment here to nudge our team.
- This repository is maintained through an internal mirror. When your change is accepted, this PR will close automatically. Don't be alarmed when it closes — that's how it merges, and your authorship is preserved.`;
}
diff --git a/.github/scripts/bridge-public-pr-to-monorepo.test.mjs b/.github/scripts/bridge-public-pr-to-monorepo.test.mjs
index a44d37f52..9a02cfb8e 100644
--- a/.github/scripts/bridge-public-pr-to-monorepo.test.mjs
+++ b/.github/scripts/bridge-public-pr-to-monorepo.test.mjs
@@ -462,7 +462,9 @@ describe('applyPatchWithConflictDetection (graceful conflict routing canary)', (
const body = buildWelcomePublicComment();
expect(body).toContain('Thanks for the contribution!');
- expect(body).toContain('A maintainer will review your PR.');
+ expect(body).toContain('A maintainer will review your PR if it is a small fix');
+ expect(body).toContain('links an issue a maintainer has accepted');
+ expect(body).toContain('may be closed without review');
expect(body).toContain('internal mirror');
expect(body).toContain('authorship is preserved');
expect(body).not.toContain('Copybara');
diff --git a/AGENTS.md b/AGENTS.md
index 07cd3aa6e..6b9db9f07 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -79,7 +79,7 @@ Shell scripts are declared in scope by `no-comments.config.jsonc`, but the sweep
## Public Mirror Rules
- This repo is generated from an allowlist. Do not rely on hidden source-only folders being present.
-- Public PRs are reviewed by maintainers and accepted changes sync back here automatically. A PR may close rather than show as merged; that is expected for this mirror.
+- Maintainers review public PRs that are small fixes or link an accepted issue; others may be closed without review (see the Pull requests section of `CONTRIBUTING.md`). A detailed issue is the preferred contribution. Accepted changes sync back here automatically. A PR may close rather than show as merged; that is expected for this mirror.
- Top-level public docs such as `README.md`, `CONTRIBUTING.md`, and `AGENTS.md` are overlay files. Keep them public-safe and standalone.
- Do not add secrets, private customer context, internal-only specs, local paths, or generated debug artifacts.
- Keep dependency updates paired with `pnpm-lock.yaml`. Run `pnpm run notices` when third-party notices may change.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index eb7f7a4f9..3af6d2d85 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,11 +1,32 @@
# Contributing to OpenKnowledge
-Thanks for contributing! Bug reports, feature requests, and pull requests are all welcome.
+Thanks for helping. The most useful thing you can send us is a detailed issue, not a pull request.
-- **Found a bug or have an idea?** [Open an issue](https://github.com/inkeep/open-knowledge/issues/new/choose).
+- **Found a bug or have an idea?** [Open an issue](https://github.com/inkeep/open-knowledge/issues/new/choose). This is the main way to contribute; see [Write an issue we can build from](#write-an-issue-we-can-build-from).
- **Question or setup help?** Ask in [Discord](https://discord.gg/VRKk2EaGHN).
-- **Ready to code?** Open a pull request against this repository.
- **Read a language other than English?** Most of our interface translations are machine-translated and have never been read by a native speaker, and we ship them anyway rather than hide them from the people who could fix them. Correcting one is the most useful thing you can do for it — see [Translate the interface](https://openknowledge.ai/docs/contribute/translations).
+- **Want to write the code yourself?** Read [Pull requests](#pull-requests) before you start.
+
+## Why issues come first
+
+Reviewing an outside pull request takes us longer than building the same change from a clear issue. We have to read code written without our context, check it for security problems, and usually rework it to fit the codebase. A good issue skips that: it costs you less time, and we build, test and review the change in our normal process.
+
+## Write an issue we can build from
+
+Use the bug report or feature request form. The issues we can act on fastest:
+
+- **Start with the problem, not the solution.** Say what you were doing, what happened, and why it matters to you.
+- **For a bug,** give steps that reproduce it, your version and platform, and any logs or screenshots.
+- **For a feature,** describe what you would see if it worked. That tells us when it is done.
+- **Point at the code if you found it.** A file, a function or a link to a line helps. Describe the fix in words.
+- **Don't paste a full patch.** Describe the fix in words. If you want to write it yourself, say so in the issue; once a maintainer accepts it (see [Pull requests](#pull-requests)), open a pull request so the change comes with the [Contributor License Agreement](./CLA.md).
+
+When a fix ships, we close your issue, and our release automation usually comments on it with the version the fix shipped in.
+
+## How credit works
+
+- **Code contributors** are people whose pull requests we accept. The commit that lands credits you as a co-author, which makes you a contributor to this repository. Code contributions require the CLA.
+- **Issue authors** are credited on the issue itself, which stays linked to the problem you found and is closed when we fix it. Filing an issue does not make you a code contributor, and it does not require the CLA.
## Development setup
@@ -73,7 +94,14 @@ A short allowlist survives: directives a tool parses (`biome-ignore lint/style/n
If lint stops you, the diagnostic names the class of comment, the fix, and links to [`lint-plugins/no-comments/README.md`](./lint-plugins/no-comments/README.md) — the full policy, including how to convert a comment worth keeping into one of the allowed forms. Deleting it is usually the right answer.
-## Opening a pull request
+## Pull requests
+
+We still accept pull requests, on these terms:
+
+- **Small fixes are welcome any time:** typos, broken links, documentation corrections and translation fixes.
+- **Anything larger needs an accepted issue first.** Open the issue and wait for a maintainer to label it `help wanted` or say in the thread that we would take a pull request. Link that issue in your PR description.
+- **A pull request without an accepted issue may be closed without review.** If the idea is good, we track it as an issue and build it ourselves.
+- **You are responsible for every line.** AI-assisted code is fine when you understand it, have run it, and can answer questions about it. We close pull requests that read as unreviewed AI output.
First-time contributors are asked to sign our [Contributor License Agreement](./CLA.md) — a bot comments a one-click signing link on your PR (Inkeep employees are exempt automatically). Please follow the checklist in our [Pull Request Template](./.github/PULL_REQUEST_TEMPLATE.md):
@@ -86,7 +114,7 @@ First-time contributors are asked to sign our [Contributor License Agreement](./
- Never include secrets, credentials, customer data, or local machine paths.
- Enable **Allow edits from maintainers** so reviewers can push fixes to your branch.
-A maintainer will review your PR; if you don't hear back within a few business days, a friendly nudge on the thread is welcome. Accepted changes land on `main` with your authorship preserved (your PR may show as closed rather than merged).
+A maintainer reviews pull requests that are small fixes or link an accepted issue; if you don't hear back within a few business days, a friendly nudge on the thread is welcome. Accepted changes land on `main` with your authorship preserved (your PR may show as closed rather than merged).
## License
diff --git a/README.md b/README.md
index a70429da2..bba4c38d0 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,7 @@ Docs for general usage: <https://openknowledge.ai/docs>.
## Contributions
-Public pull requests or issues are welcome!
+The best way to contribute is a detailed [issue](https://github.com/inkeep/open-knowledge/issues/new/choose): we build and review the change ourselves. Pull requests are welcome for small fixes, and for larger changes once a maintainer has accepted the issue.
See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
diff --git a/docs/content/contribute/translations.mdx b/docs/content/contribute/translations.mdx
index f11a69015..c165d1ae8 100644
--- a/docs/content/contribute/translations.mdx
+++ b/docs/content/contribute/translations.mdx
@@ -66,4 +66,4 @@ packages/app/src/locales/<locale>/messages.po
## A language that isn't on the list
-Open an [issue](https://github.com/inkeep/open-knowledge/issues) before starting work on one. Then follow the instructions above to provide a complete language set. Don't forget to add the language to the list of available UI languages so other users can select your translation set from within the desktop application!
+Open an [issue](https://github.com/inkeep/open-knowledge/issues) before starting work on one, and wait for a maintainer to accept it: a new language is larger than a small fix, so it follows the [pull request rules](https://github.com/inkeep/open-knowledge/blob/main/CONTRIBUTING.md#pull-requests). Then follow the instructions above to provide a complete language set. Don't forget to add the language to the list of available UI languages so other users can select your translation set from within the desktop application!