From bf7ee55dd4d302184bc0fe1038b437e9e577007d Mon Sep 17 00:00:00 2001 From: Dima Date: Fri, 5 Jun 2026 18:27:04 +0200 Subject: [PATCH] update contributing --- .changeset/README.md | 15 ++++++++------- .github/pull_request_template.md | 17 +++++++++++++++++ AGENTS.md | 2 +- CLA.md | 4 +++- CODE_OF_CONDUCT.md | 25 +++++++++++++++++++++++++ CONTRIBUTING.md | 29 ++++++++++++++++++++++++++++- README.md | 2 +- SECURITY.md | 18 ++++++++++++++++++ 8 files changed, 101 insertions(+), 11 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 SECURITY.md diff --git a/.changeset/README.md b/.changeset/README.md index 1dc25842..68ab97f8 100644 --- a/.changeset/README.md +++ b/.changeset/README.md @@ -20,13 +20,14 @@ 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 change for consumers (rename, removal, schema) | `minor` | -| New feature, additive API surface | `minor` | -| Bug fix, internal change, no user-visible API 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), every change is either `minor` (new behavior or breaking change) or `patch` (bug fix / refinement). This lets us ship breaking changes without prematurely advertising a 1.0 stability promise. +| 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` | + +**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. **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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..26fcb96d --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,17 @@ +## Summary + +- + +## Verification + +- + +## Checklist + +- [ ] I ran the smallest relevant local check, or explained why I could not. +- [ ] I added tests or a manual verification note for behavior changes. +- [ ] I added a changeset for runtime behavior changes, or this PR does not need one. +- [ ] I updated docs when behavior, commands, or contributor flow changed. +- [ ] I updated `bun.lock` and `THIRD_PARTY_NOTICES.md` if dependencies changed. +- [ ] I did not include secrets, credentials, customer data, local machine paths, or generated debug artifacts. +- [ ] I understand external contributors must sign the CLA when prompted. diff --git a/AGENTS.md b/AGENTS.md index ace20380..518d1031 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,7 +59,7 @@ bun run dev Every behavior-changing PR ships a `.changeset/.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/.md`. -- Front-matter: at minimum `'@inkeep/open-knowledge': patch`. Open Knowledge follows semver with a **pre-1.0 shift-down**: while we're below `1.0.0`, what semver would call a major (breaking API change) is encoded as `minor`, and what semver would call a minor (new feature) is encoded as `patch`. Most changesets are `patch`. `minor` is rare — reserve it for large API contract changes or large feature additions. **Never declare `major` pre-1.0** (see the `"//"` line in `.changeset/config.json`). +- 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`). - 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/open-knowledge-core@0.5.0-beta.6`) — 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/CLA.md b/CLA.md index e95acadb..53996e71 100644 --- a/CLA.md +++ b/CLA.md @@ -1,4 +1,4 @@ -> Based on the Apache Individual Contributor License Agreement (ICLA) V2.2, with Inkeep, Inc. as the grantee. It is a copyright and patent **license**, not an assignment, so you keep full ownership of your contributions. The license-grant and representation clauses (sections 1 to 8) are the verbatim Apache text; the Foundation's nonprofit-specific covenant and the paper contact-form fields are omitted. +> Adapted from the Apache Individual Contributor License Agreement (ICLA) V2.2, with Inkeep, Inc. as the grantee. It is a copyright and patent **license**, not an assignment, so you keep full ownership of your contributions. # Inkeep Individual Contributor License Agreement @@ -29,3 +29,5 @@ You accept and agree to the following terms and conditions for Your present and --- **How to sign.** Open a pull request on the public repository. The CLA-assistant bot will comment with a link to sign this Agreement — a one-time, roughly 30-second authenticated click recorded against your GitHub identity that covers all of your future contributions. Inkeep employees and project bots are allowlisted and are not prompted. + +If your employer requires a Corporate Contributor License Agreement, comment on your pull request and an Inkeep maintainer will coordinate next steps. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..7637d0aa --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,25 @@ +# Code of Conduct + +## Our Pledge + +We want Open Knowledge to be a respectful, practical, and welcoming project for contributors and maintainers. + +## Expected Behavior + +- Be respectful and constructive. +- Keep discussions focused on the work. +- Assume good intent, and ask clarifying questions when something is unclear. +- Accept maintainer decisions about scope, priority, and project direction. + +## Unacceptable Behavior + +- Harassment, threats, or personal attacks. +- Discriminatory language or conduct. +- Publishing private information without permission. +- Repeatedly disrupting project discussions after a maintainer asks you to stop. + +## Enforcement + +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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfd170db..4812df0d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,10 +16,17 @@ Review and merge decisions happen in the internal mirror so that public and inte 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. +- **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. If internal checks fail, a maintainer will summarize the failure on the public PR and ask for changes. - **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. +- **Stale automation may comment on inactive PRs.** If your PR is still relevant, reply with the current status. A human maintainer can keep active work moving even when review is happening internally. - **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. +## Contributor License Agreement + +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. + ## Development Setup ```bash @@ -80,6 +87,26 @@ bun run test - 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. +- Follow the [Code of Conduct](./CODE_OF_CONDUCT.md). +- Report vulnerabilities through [SECURITY.md](./SECURITY.md), not in public issues. + +## Changesets + +Every behavior-changing PR needs a `.changeset/.md` file. The body becomes the user-facing release note, so write what changed for users rather than a commit-message summary. Skip changesets for docs-only edits, test-only edits, or CI-only edits that do not change runtime behavior. + +Create a changeset with: + +```bash +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. +- 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. ## Force-Push and Maintainer Iteration diff --git a/README.md b/README.md index fa8fc1cf..f6d68b88 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This public repository is mirrored from Inkeep's internal monorepo with Copybara Public pull requests are welcome. When a public PR opens here, automation mirrors it into the internal monorepo for review and merge. After the internal PR lands, Copybara syncs the accepted change back to this repository. -See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contribution flow and [AGENTS.md](./AGENTS.md) for agent-facing development guidance. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contribution flow, including the [Contributor License Agreement](./CLA.md), and [AGENTS.md](./AGENTS.md) for agent-facing development guidance. ## Prerequisites diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..a7463fd9 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,18 @@ +# Security Policy + +## Reporting a Vulnerability + +Please do not open a public GitHub issue for a suspected vulnerability. + +Report security issues by emailing incidents@inkeep.com with: + +- A description of the issue and affected component. +- Steps to reproduce or proof-of-concept details, if available. +- 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. + +## Supported Versions + +Open Knowledge is pre-1.0. Security fixes are shipped through the latest public release and the public mirror's `main` branch.