diff --git a/.github/scripts/bridge-public-pr-to-monorepo.mjs b/.github/scripts/bridge-public-pr-to-monorepo.mjs index 9bd24b0b1..d955f77db 100644 --- a/.github/scripts/bridge-public-pr-to-monorepo.mjs +++ b/.github/scripts/bridge-public-pr-to-monorepo.mjs @@ -356,54 +356,52 @@ ${buildBridgeMetadata(publicPr, mirrorPath)}`; return body; } -function buildPublicComment({ publicPr, internalPr, status, details }) { +function buildPublicComment({ publicPr, status, details }) { if (status === 'synced') { return `${BRIDGE_COMMENT_MARKER} -Thanks for the contribution! Your PR has been mirrored into Inkeep's internal monorepo, where review and merge happen. Your commit attribution is preserved as @${publicPr.user.login}. +Thanks for the contribution! A maintainer will review and merge your PR. Your commit attribution is preserved as @${publicPr.user.login}. **What happens next:** -- An Inkeep maintainer will review the internal mirror PR. -- Reviewer comments are not automatically mirrored back to this thread. If you don't hear from us within a few business days, please comment here to nudge — that's the right thing to do. -- Once merged internally, the change will sync back to this repository and this PR will close automatically (don't be alarmed when it closes — that's how it lands). +- A maintainer will review your PR. +- If you don't hear back within a few business days, please comment here to nudge — that's the right thing to do, not annoying. +- When your change is accepted, this PR closes automatically. Don't be alarmed when it closes — that's how it merges, and your authorship is preserved. -**For Inkeep maintainers** (link goes to a private repo and is not accessible to external contributors): ${internalPr.html_url} - -See the repository's CONTRIBUTING.md for more context on how public PRs flow. This comment will be updated as the bridge state changes.`; +This comment will be updated as the status changes.`; } if (status === 'no-op') { return `${BRIDGE_COMMENT_MARKER} -I checked this public PR, but there was no new diff to port into \`agents-private\`. +I checked this PR, but there was no new change to sync. ${details}`; } if (status === 'closed') { return `${BRIDGE_COMMENT_MARKER} -The public PR was closed without merge, so the matching internal PR was closed as well. +This PR was closed without merging. ${details}`; } if (status === 'merged-upstream') { return `${BRIDGE_COMMENT_MARKER} -This public PR was merged directly in the public repo. The matching monorepo PR was left open for manual follow-up because \`agents-private\` remains the source of truth. +This PR was merged directly here. A maintainer will make sure the change is reconciled on our side. ${details}`; } if (status === 'conflicts') { return `${BRIDGE_COMMENT_MARKER} -Thanks for the contribution! Your PR has been mirrored into Inkeep's internal monorepo, but it **could not be merged automatically**: the change overlaps edits in the internal source that aren't visible on this public mirror, so it needs a maintainer to reconcile by hand. +Thanks for the contribution! Your PR **could not be merged automatically**: it overlaps other changes that aren't visible here, so a maintainer needs to reconcile it by hand. -**No action is needed from you.** Your PR is already based on the latest \`${publicPr.base.repo.full_name}\` main; the divergence is internal to the mirror, not something to fix from your branch. Your commit attribution is preserved as @${publicPr.user.login}. +**No action is needed from you.** Your PR is already based on the latest \`${publicPr.base.repo.full_name}\` main; the overlap is on our side, not something to fix from your branch. Your commit attribution is preserved as @${publicPr.user.login}. -An Inkeep maintainer will resolve the conflicts on the internal mirror PR and land it; this PR will close automatically once it merges internally. This comment will be updated as the bridge state changes.`; +A maintainer will resolve it and land your change; this PR will close automatically once it merges. This comment will be updated as the status changes.`; } return `${BRIDGE_COMMENT_MARKER} -I could not sync this public PR into \`agents-private\` automatically. +I could not sync this PR automatically. A maintainer will look into it. ${details}`; } @@ -768,9 +766,9 @@ async function syncPublicPr() { publicPr, status: 'failed', details: - 'The diff could not be applied to the internal monorepo. This is a ' + + 'The diff could not be applied on our side. This is a ' + 'bridge-side issue, not a problem with your PR (which is already based ' + - 'on the latest public base); an Inkeep maintainer will look into it.' + + 'on the latest public base); a maintainer will look into it.' + `\n\n\`\`\`\n${applyResult.message}\n\`\`\``, }), }); @@ -864,8 +862,7 @@ async function syncPublicPr() { body: buildPublicComment({ publicPr, status: 'no-op', - details: - 'The diff already appears to be present on the internal base branch, so no new monorepo PR was opened.', + details: 'The change already appears to be present, so there was nothing new to sync.', }), }); return; @@ -979,7 +976,7 @@ async function closeLinkedInternalPr() { publicPr, internalPr, status: 'merged-upstream', - details: `Matching internal PR: [#${internalPr.number}](${internalPr.html_url})`, + details: '', }), }); return; @@ -1019,7 +1016,7 @@ async function closeLinkedInternalPr() { body: buildPublicComment({ publicPr, status: 'closed', - details: `Closed matching internal PR [#${internalPr.number}](${internalPr.html_url}).`, + details: '', }), }); } diff --git a/.github/scripts/bridge-public-pr-to-monorepo.test.mjs b/.github/scripts/bridge-public-pr-to-monorepo.test.mjs index 34afcf266..9198959bb 100644 --- a/.github/scripts/bridge-public-pr-to-monorepo.test.mjs +++ b/.github/scripts/bridge-public-pr-to-monorepo.test.mjs @@ -433,13 +433,13 @@ describe("syncPublicPr metadata-event composition (conflict-hold fail-open guard expect(r.draftMutation).toBeNull(); expect(r.comment).toContain("No action is needed from you"); expect(r.comment.toLowerCase()).not.toContain("rebase"); - expect(r.comment).not.toContain("review and merge happen"); // not the 'synced' body + expect(r.comment).not.toContain("review and merge your PR"); // not the 'synced' body }); test("a metadata event on a clean PR readies it and posts 'synced'", async () => { const r = await runMetadataSync({ headCommitMessage: CLEAN_HEAD, internalPrStartsDraft: true }); expect(r.draftMutation).toBe("to-ready"); - expect(r.comment).toContain("review and merge happen"); // the 'synced' body + expect(r.comment).toContain("review and merge your PR"); // the 'synced' body }); test("a metadata event on a non-draft PR whose head now carries conflicts re-drafts it", async () => { diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b930fe844..0ef794299 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,94 +1,64 @@ # Contributing to OpenKnowledge -OpenKnowledge is developed in Inkeep's internal monorepo and mirrored to this public repository with Copybara. Public contributions should still start here: open a pull request against `inkeep/open-knowledge`. +Thanks for contributing! Bug reports, feature requests, and pull requests are all welcome. -## How Public PRs Flow +- **Found a bug or have an idea?** [Open an issue](https://github.com/inkeep/open-knowledge/issues/new/choose). +- **Question or setup help?** Ask in [Discord](https://discord.com/invite/YujKpFN49). +- **Ready to code?** Open a pull request against this repository. -1. Open a PR against this repository. -2. Automation mirrors the PR into `inkeep/agents-private` under `public/open-knowledge/`. -3. Maintainers review and merge the internal PR. -4. Copybara syncs the accepted change back to this repository and your public PR is closed automatically (not merged — the change lands via the mirror sync, not via the public PR). +## Development setup -Review and merge decisions happen in the internal mirror so that public and internal development stay on the same history. - -## What to Expect After Opening a PR - -A short orientation, because the flow is unusual: - -- **Within ~1 minute** a bot will post a sticky comment on your PR indicating that an internal mirror PR has been opened. The link in that comment points to a private repo and won't be accessible to you; that's expected. -- **Automated review** runs on every public PR via an LLM-based code review (Claude). Full lint, type checks, and tests run internally after the bridge mirrors your changes — results are not surfaced back to your public PR. -- **Maintainer review happens in the internal mirror.** Reviewer comments are **not auto-mirrored back to your PR**. If you don't hear back within a few business days, please comment on your PR to nudge — that's the right thing to do, not annoying. -- **Your PR will be closed (not merged)** once the change has been merged internally and synced back. The mirrored commit on `main` is attributed to our sync bot for technical reasons, but the PR history and internal commit preserve your original authorship. - -## Development Setup +A fresh clone builds and tests with no environment variables: ```bash bun install -bun run check +bun run check # lint, typecheck, and tests ``` -Run the app locally: +Run the editor app (http://localhost:5173): ```bash -bun run --filter @inkeep/open-knowledge-app dev +cd packages/app && bun run dev ``` -Run the docs site locally: +Run the docs site: ```bash -cd docs -bun run dev +cd docs && bun run dev ``` -### Environment Variables - -OpenKnowledge requires no environment variables for development — `bun install && bun run check` works in a fresh clone. To start the dev server, see the commands above. See `.env.example` for optional dev/observability env vars (OpenTelemetry, custom dev server port). +See `.env.example` for optional settings (OpenTelemetry, a custom dev port). ### Toolchain -The repository pins `Bun 1.3.13+` and `Node.js 24+` via `.bun-version`, `.node-version`, and `package.json` `engines`. If you use a version manager: - -- `fnm install` (reads `.node-version`) -- `volta install node@24` -- `mise install` (reads `.node-version`) +The repo pins **Bun 1.3.13+** and **Node.js 24+** (via `.bun-version`, `.node-version`, and `engines`). With a version manager, use `fnm install`, `mise install`, or `volta install node@24`. On older Node, `bun install` warns `EBADENGINE` and builds or tests may fail — pin Node 24+ first. -If you're on a different Node version, `bun install` will warn about `EBADENGINE`. The install usually succeeds anyway, but tests and builds may not — pin Node 24+ before reporting issues. - -## Useful Commands +## Common commands ```bash -bun run format # Format with Biome -bun run lint # Lint with Biome -bun run typecheck # TypeScript checks through Turbo -bun run test # Test through Turbo -bun run build # Build all workspaces -bun run check # Public PR gate: lint, typecheck, and tests +bun run format # format (Biome) +bun run lint # lint (Biome) +bun run typecheck # TypeScript +bun run test # tests +bun run build # build all packages +bun run check # lint + typecheck + test ``` -For targeted work, run package commands from the package directory: +Run a single package's scripts from its directory, e.g. `cd packages/app && bun run test`. -```bash -cd packages/app -bun run test -``` +## Opening a pull request -## Contribution Guidelines +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). - Keep PRs focused and small enough to review. -- Include tests or a clear manual verification note for behavior changes. -- Run `bun run check` before requesting review. -- Commit `bun.lock` when dependency changes require it. -- Run `bun run notices` and include `THIRD_PARTY_NOTICES.md` changes when dependency changes affect third-party notices. -- Do not include secrets, credentials, customer data, local machine paths, or generated debug artifacts. - -## Force-Push and Maintainer Iteration - -If a maintainer needs to push fixes to your PR during review, they may either ask you to make the changes or push directly to your fork branch (if you've enabled "allow edits from maintainers" on your PR). Force-pushing to your own branch after a maintainer commit may discard their work — please coordinate via the PR thread before force-pushing if a maintainer has been actively iterating. Since maintainer comments in the internal mirror are not auto-mirrored, a maintainer who is actively iterating will typically post directly on your public PR when coordination is needed. - -## Public Export Boundary +- Add tests — or a clear manual-verification note — for behavior changes. +- Run `bun run check` and confirm it passes. +- Commit `bun.lock` when dependencies change, and run `bun run notices` to refresh `THIRD_PARTY_NOTICES.md` if third-party packages changed. +- Never include secrets, credentials, customer data, or local machine paths. +- Enable **Allow edits from maintainers** so reviewers can push fixes to your branch. -Only source code, public docs, and build or development scripts are exported here. Internal planning notes, reports, specs, and agent workspace files are intentionally not part of the public mirror. +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). ## License -OpenKnowledge is licensed under the [GNU General Public License v3.0 or later](./LICENSE) (`GPL-3.0-or-later`). By submitting a contribution, you agree that it is licensed under the same terms. +By contributing, you agree that your work is licensed under the [GNU General Public License v3.0 or later](./LICENSE) (`GPL-3.0-or-later`), the same license as OpenKnowledge.