Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.ymlindex 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: textareaid: logsattributes:diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.ymlindex 5215df319..23fd5913d 100644--- a/.github/ISSUE_TEMPLATE/feature_request.yml+++ b/.github/ISSUE_TEMPLATE/feature_request.yml@@ -6,7 +6,7 @@ body:- type: markdownattributes: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: textareaid: problemattributes:@@ -20,6 +20,20 @@ body:label: Proposed solutionvalidations: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: dropdownid: areaattributes:diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex 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.mjsindex 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.mjsindex 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.mdindex 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.mdindex 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/nIf 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).## Licensediff --git a/README.md b/README.mdindex 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.mdxindex 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!