Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(contributing): clarify review feedback

Dima0caaa4969b67
diff --git a/.changeset/README.md b/.changeset/README.md
index 68ab97f8d..12b5d947c 100644
--- a/.changeset/README.md
+++ b/.changeset/README.md
@@ -20,19 +20,19 @@ holds three bits of information:
**While Open Knowledge is pre-1.0, NEVER declare a `major` bump in a changeset.** OK uses a modified semver where the bump types map differently:
-| What you want to communicate | OK pre-1.0 bump type |
-| ------------------------------------------------------------- | -------------------- |
-| Breaking API, schema, or CLI change | `minor` |
-| Large new surface | `minor` |
-| Bug fix, UI improvement, or small user-visible addition | `patch` |
-| Internal change with no user-visible runtime impact | `patch` |
+| What you want to communicate | OK pre-1.0 bump type |
+| ----------------------------------------------------------------------- | -------------------- |
+| Breaking API, schema, or CLI change | `minor` |
+| Large new surface (new CLI command, MCP tool, or editor feature) | `minor` |
+| Bug fix, UI improvement, or small addition to an existing surface | `patch` |
+| Internal change with no user-visible runtime impact | `patch` |
-**Why:** under standard semver, going from `0.X.Y` to `1.0.0` is a once-in-a-product-lifetime decision. Until OK explicitly takes a major (decided by the team, not by an individual changeset), breaking changes and large surfaces use `minor`, while fixes and smaller user-visible additions use `patch`. This lets us ship breaking changes without prematurely advertising a 1.0 stability promise.
+**Why:** under standard semver, going from `0.X.Y` to `1.0.0` is a once-in-a-product-lifetime decision. Until OK explicitly takes a major (decided by the team, not by an individual changeset), breaking changes and large surfaces use `minor`, while fixes and smaller additions to existing surfaces use `patch`. This lets us ship breaking changes without prematurely advertising a 1.0 stability promise.
**Mechanic:** the OK fixed-group (`@inkeep/open-knowledge`, `-core`, `-server`, `-app`, `-desktop`) bumps in lock-step on the highest declared bump type across all queued changesets. A single `major` declaration on any one package pulls the entire group to `1.0.0` — once. Don't be that changeset.
When `1.0.0` does eventually ship, this convention will be retired and standard semver resumes.
-> Authoring tip: run `bun changeset` from anywhere under `public/open-knowledge/` — the CLI walks up to find this folder. Don't hand-create files; the tool's interactive flow asks for bump types in order and writes a well-formed frontmatter block. Per the convention above, only pick `minor` or `patch`.
+> Authoring tip: run `bun run changeset` from anywhere under `public/open-knowledge/` — the CLI walks up to find this folder. Don't hand-create files; the tool's interactive flow asks for bump types in order and writes a well-formed frontmatter block. Per the convention above, only pick `minor` or `patch`.
> SKILL.md metadata is synced automatically by the VP workflow via [`scripts/sync-skill-version.sh`](../scripts/sync-skill-version.sh). You don't need to bump `packages/server/assets/skills/open-knowledge/SKILL.md`'s `metadata.version:` by hand — `bun changeset version` (in CI) bumps the package.json files, then the sync script propagates the new version into SKILL.md. The same script can be run manually from `public/open-knowledge/` if you ever need to re-sync after a hand edit.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 18287a604..b6135b61a 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,7 +4,7 @@
## How this was verified
-<!-- How you tested: `bun run check` output, manual steps, before/after screenshots for UI changes. -->
+<!-- What did you run or observe to confirm the change works? (test command, screenshot, manual steps) -->
## Checklist
diff --git a/AGENTS.md b/AGENTS.md
index a161dc8c9..e71592031 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -59,7 +59,7 @@ bun run dev
Every behavior-changing PR ships a `.changeset/<kebab-name>.md` file. The body becomes the user-facing entry on the next beta's GitHub Release and on the aggregated stable Release notes — that's how npm consumers and DMG auto-update users learn what changed. Write release-note copy, not a commit-message reprise.
- Create one with `bun run changeset`, or hand-write a file named `.changeset/<descriptive-kebab-slug>.md`.
-- Bump type: use `patch` for bug fixes, UI improvements, and small user-visible additions; use `minor` for breaking API, schema, or CLI changes, and for large new surfaces. **Never declare `major` pre-1.0** (see the `"//"` line in `.changeset/config.json`).
+- Bump type: use `patch` for bug fixes, UI improvements, and small additions to existing surfaces; use `minor` for breaking API, schema, or CLI changes, and for large new surfaces such as a new CLI command, MCP tool, or editor feature. Most changesets are `patch`. **Never declare `major` pre-1.0** (see the `"//"` line in `.changeset/config.json`).
- Body should lead with the user-visible verb, name the affected command or surface in a code-span, and (if relevant) show before/after. Skip internal references like spec IDs or story numbers — those rot and aren't visible to readers of the public release notes.
- Don't write inline references to sibling-package versions (e.g. `@inkeep/[email protected]`) — the fixed-group lock-step bumps are computed at release time and any number you'd write would be wrong.
- Skip changesets for docs-only edits, test-only edits, or CI-only edits that don't change runtime behavior.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 7637d0aa7..aaa205606 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -22,4 +22,4 @@ We want Open Knowledge to be a respectful, practical, and welcoming project for
Maintainers may remove comments, close issues or pull requests, limit participation, or block users when behavior harms the project or its contributors.
-To report a conduct concern, contact an Inkeep maintainer privately when possible. Include relevant links, screenshots, or context.
+To report a conduct concern, email [email protected] privately when possible. Include relevant links, screenshots, or context.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b09871394..5f25d5d15 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,7 +25,7 @@ A short orientation, because the flow is unusual:
External contributors must sign the [Inkeep Individual Contributor License Agreement](./CLA.md). After you open a PR, the CLA assistant will comment with a signing link. You only need to sign once for future contributions.
-If your employer requires a Corporate Contributor License Agreement, comment on your PR and an Inkeep maintainer will coordinate next steps.
+For corporate CLAs, see [CLA.md](./CLA.md).
## Development Setup
@@ -102,8 +102,8 @@ bun run changeset
Open Knowledge is pre-1.0. Use these bump levels:
-- `patch` for bug fixes, UI improvements, and small user-visible additions.
-- `minor` for breaking API, schema, or CLI changes, and for large new surfaces.
+- `patch` for bug fixes, UI improvements, and small additions to existing surfaces.
+- `minor` for breaking API, schema, or CLI changes, and for large new surfaces such as a new CLI command, MCP tool, or editor feature.
- Never declare `major` while Open Knowledge is pre-1.0.
The packages release in a fixed group, so do not write inline references to sibling package versions in the changeset body. Release tooling computes those versions at publish time.
diff --git a/SECURITY.md b/SECURITY.md
index a7463fd94..087f3e3a7 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -11,7 +11,7 @@ Report security issues by emailing [email protected] with:
- The impact you believe the issue may have.
- Any suggested mitigation.
-We will acknowledge reports as soon as practical and coordinate disclosure timelines directly with the reporter.
+We aim to acknowledge reports within 5 business days and coordinate disclosure timelines directly with the reporter. If you have not heard back, reply to your original email.
## Supported Versions