From eb81675efae16ebfc69110d39cc480fc2a399ad4 Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Tue, 1 Sep 2026 02:31:33 -0500 Subject: [PATCH 1/4] docs: add contributing and code of conduct Add the two governance documents the repository still lacks before a public release. CONTRIBUTING.md is written against this repository rather than from a template: the real toolchain (Node 22+, pnpm 10.34.0 via Corepack, rust-toolchain.toml), the real script names, the worktree-per-branch convention, the signed-commit requirement including the pre-flight user.signingkey and gpg.format checks, and an honest description of the phase 1 conformance lock, including which paths it pins and the two-commit repin process. Contributors are told not to repin speculatively. CODE_OF_CONDUCT.md adapts the Contributor Covenant 2.1 principles and enforcement ladder, with attribution, and points reporting at the GitHub report control plus a private channel. LICENSE and SECURITY.md are deliberately not included here. They are carried by the release-infrastructure branch (#63); adding them in both places would guarantee a conflict. README.md is left untouched for the same reason: #63 already appends to it, and the links to these two files should be added once that lands. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CODE_OF_CONDUCT.md | 84 +++++++++++++++++++++++++ CONTRIBUTING.md | 152 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..bd04f392 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,84 @@ +# Code of Conduct + +## Our commitment + +OpenCoven Chat is built in the open. Everyone who takes part — reporting bugs, +reviewing code, answering questions, or shipping features — should be able to +do so without harassment, condescension, or hostility. + +We commit to keeping participation in this project a respectful experience for +everyone, regardless of age, body size, visible or invisible disability, +ethnicity, sex characteristics, gender identity and expression, level of +experience, education, socio-economic status, nationality, personal appearance, +race, religion, or sexual identity and orientation. + +## Expected behaviour + +- Assume good faith. Most disagreements are misunderstandings about context. +- Give feedback on the work, not the person. "This function has a race + condition" is useful; "you clearly don't know what you're doing" is not. +- Accept feedback on your own work the same way you would want to give it. +- Be explicit about uncertainty. "I think" and "I'm not sure" are strengths in + a technical discussion. +- Respect that maintainers have limited time and may close or defer work that + does not fit the project's direction. +- Respect people's stated names and pronouns. + +## Unacceptable behaviour + +- Harassment, intimidation, stalking, or unwelcome sexual attention of any kind. +- Personal, demeaning, or discriminatory comments and slurs. +- Publishing someone's private information without their explicit permission. +- Sustained disruption of discussions, issues, or reviews. +- Deliberately introducing malicious code, or misrepresenting the safety or + provenance of a contribution. +- Encouraging or defending any of the above. + +## Scope + +This Code of Conduct applies in all project spaces — the repository, issues, +pull requests, discussions, and releases — and applies when an individual is +representing the project in public spaces. + +## Reporting + +Report unacceptable behaviour privately to the maintainers: + +- Use GitHub's **Report content** control on the specific comment, issue, or + pull request, and +- Contact the maintainers through the OpenCoven Discord + (https://discord.gg/opencoven) and ask for a private channel. + +Do not post details of an incident publicly before the maintainers have had a +chance to respond. + +All reports are reviewed and investigated promptly and fairly. Maintainers are +obligated to respect the privacy and security of the reporter. Maintainers who +do not follow or enforce this Code of Conduct in good faith may face temporary +or permanent repercussions as determined by other members of the project's +leadership. + +## Enforcement + +Maintainers are responsible for clarifying and enforcing these standards. They +have the right and responsibility to remove, edit, or reject comments, commits, +code, issues, and other contributions that are not aligned with this Code of +Conduct, and will communicate reasons for moderation decisions when +appropriate. + +Consequences are proportionate to the impact of the behaviour: + +1. **Correction** — a private written warning explaining what was + inappropriate, possibly with a request for a public apology. +2. **Warning** — a warning with consequences for continued behaviour, including + a defined period of no interaction with the people involved. +3. **Temporary ban** — a temporary ban from any interaction with the project. +4. **Permanent ban** — a permanent ban from any public interaction with the + project. + +## Attribution + +This Code of Conduct is adapted from the principles and enforcement structure +of the [Contributor Covenant](https://www.contributor-covenant.org), version +2.1, which is available under the Creative Commons Attribution 4.0 +International license. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..1e05acb0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,152 @@ +# Contributing to OpenCoven Chat + +Thanks for wanting to help. OpenCoven Chat is a Tauri desktop client with a +deliberately narrow native surface and a cryptographic conformance lock, so a +few of the rules below are stricter than a typical web project. Read the +sections that apply to your change before you open a pull request. + +## Before you start + +- For anything larger than a bug fix or a docs correction, open an issue first + and describe the change. Large unsolicited pull requests are hard to land. +- Check the open pull requests — a lane may already exist for what you want. +- Security issues do **not** go through pull requests. See + [`SECURITY.md`](SECURITY.md). + +## Development setup + +Requirements: + +- Node.js 22+ (24 recommended) +- pnpm 10.34.0 via Corepack (`corepack enable`) +- Rust stable toolchain (see [`rust-toolchain.toml`](rust-toolchain.toml)) +- Tauri desktop prerequisites for your platform + +```bash +corepack pnpm install --frozen-lockfile +corepack pnpm dev # web layer only, in a browser +corepack pnpm app:dev # full Tauri desktop shell +``` + +The app runs standalone. A Coven Cave connection is optional and is opted into +from the source bar inside the app. + +## Branching and pull requests + +`main` is the release branch. Use a short-lived branch and a pull request for +every change: + +```bash +git worktree add -b / .worktrees/ origin/main +cd .worktrees/ +``` + +Branch name prefixes: `feat/`, `fix/`, `chore/`, `docs/`, `ci/`, `refactor/`, +`test/`. + +Pull request expectations: + +- One logical change per pull request. Split unrelated work into lanes. +- Describe what changed, why, and how you verified it. Paste the commands you + ran and their results. +- Keep the diff free of unrelated formatting churn. +- Update documentation in the same pull request as the behaviour it describes. + +## Commits must be signed + +Every commit must be cryptographically signed and show as **Verified** on +GitHub. Unsigned commits will be rejected. + +```bash +git commit -S -m "feat: short imperative summary" +``` + +Confirm your signing configuration before your first commit: + +```bash +git config --get user.signingkey # must return a key +git config --get gpg.format # ssh, openpgp, or x509 +git log -1 --show-signature # must report a good signature +``` + +Commit messages use a `type: summary` first line in the imperative mood, kept +under 72 characters, with detail in the body. + +## Verification + +Run these before pushing. Pull requests that fail them will not be merged. + +```bash +corepack pnpm typecheck # TypeScript, no emit +corepack pnpm lint # Biome, must be clean +corepack pnpm test # unit suites (normal + heavy; heavy is slow) +corepack pnpm build # production web build +``` + +If you touched Rust: + +```bash +corepack pnpm cargo:fmt +corepack pnpm cargo:clippy # warnings are denied +corepack pnpm cargo:test +``` + +End-to-end tests use Playwright and bind a fixed preview port: + +```bash +corepack pnpm test:e2e +``` + +New behaviour needs a test. Bug fixes need a regression test that fails before +the fix. + +## Code style + +Formatting and linting are enforced by [Biome](https://biomejs.dev) — two-space +indentation, 100-column lines, single quotes in TypeScript, double quotes in +JSX. Run `corepack pnpm format` rather than hand-formatting. Do not disable +lint rules with blanket suppressions; a `biome-ignore` must be a single line +directly above the diagnostic and must carry a reason. + +Comment only what needs clarification. Prefer explicit types at module +boundaries and narrow, well-named modules over large ones. + +## The conformance lock + +`phase1-conformance.lock.json` cryptographically pins the Rust host, the +contents of `scripts/`, and two workflow files (`ci.yml` and +`client-v1-conformance.yml`). If your change touches any pinned path, the +conformance suite will fail until the lock is repinned, which is a two-commit +process: + +1. Commit the functional change on its own. +2. Commit a second change updating the pinned revision, tree, and blob hashes + to that first commit, plus the byte-count and digest rows in + [`docs/phase1-conformance.md`](docs/phase1-conformance.md) and the + expectations in `src/phase1-conformance-lock.test.ts`. + +If you are not sure whether your change is pinned, say so in the pull request +and a maintainer will help. Do not repin speculatively. + +## Security-sensitive areas + +Changes in these areas get extra scrutiny and should be proposed in an issue +first: + +- The Tauri capability set and any new native command. +- Keyring, pairing, or credential handling in `src-tauri/`. +- Anything that widens what the webview can reach. +- The release and packaging workflows. + +The native surface is intentionally minimal. "It would be convenient" is not +sufficient justification for widening it. + +## Code of conduct + +Participation is governed by the +[Code of Conduct](CODE_OF_CONDUCT.md). + +## License + +By contributing, you agree that your contributions are licensed under the MIT +License, as described in [`LICENSE`](LICENSE). From 255ebf4550ef89a9a857c8faaf7fda8ff35f81af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Val=20Alexander=20=F0=9F=91=91?= Date: Tue, 1 Sep 2026 03:18:55 -0500 Subject: [PATCH 2/4] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e05acb0..3cd2807e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ sections that apply to your change before you open a pull request. Requirements: -- Node.js 22+ (24 recommended) +- Node.js 24.18.0+ (24 recommended) - pnpm 10.34.0 via Corepack (`corepack enable`) - Rust stable toolchain (see [`rust-toolchain.toml`](rust-toolchain.toml)) - Tauri desktop prerequisites for your platform From cfa077bb538afbb074539f483972e9db525cc50a Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Tue, 1 Sep 2026 22:52:26 -0500 Subject: [PATCH 3/4] docs: correct governance references Align the documented Node pin and Phase 1 authority scope with current main. Clarify conduct reporting channels and keep security reports on the SECURITY.md path.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CODE_OF_CONDUCT.md | 7 +++++-- CONTRIBUTING.md | 15 +++++++++------ 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index bd04f392..ce194b50 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -42,13 +42,16 @@ representing the project in public spaces. ## Reporting -Report unacceptable behaviour privately to the maintainers: +Report unacceptable behaviour through one of these channels: - Use GitHub's **Report content** control on the specific comment, issue, or - pull request, and + pull request for GitHub-hosted content; or - Contact the maintainers through the OpenCoven Discord (https://discord.gg/opencoven) and ask for a private channel. +Security vulnerabilities are handled separately; follow +[`SECURITY.md`](SECURITY.md). + Do not post details of an incident publicly before the maintainers have had a chance to respond. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3cd2807e..a02dfcab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ sections that apply to your change before you open a pull request. Requirements: -- Node.js 24.18.0+ (24 recommended) +- Node.js 24.18.1 (the package engine accepts `>=24.18.0 <25`) - pnpm 10.34.0 via Corepack (`corepack enable`) - Rust stable toolchain (see [`rust-toolchain.toml`](rust-toolchain.toml)) - Tauri desktop prerequisites for your platform @@ -113,11 +113,14 @@ boundaries and narrow, well-named modules over large ones. ## The conformance lock -`phase1-conformance.lock.json` cryptographically pins the Rust host, the -contents of `scripts/`, and two workflow files (`ci.yml` and -`client-v1-conformance.yml`). If your change touches any pinned path, the -conformance suite will fail until the lock is repinned, which is a two-commit -process: +`phase1-conformance.lock.json` cryptographically pins the Phase 1 authority +graph: the Chat, SDK, Cave, Coven, and harness revisions; selected Chat host +files; selected harness scripts and both workflow files +(`.github/workflows/ci.yml` and `.github/workflows/client-v1-conformance.yml`); +release and evidence metadata; and the Windows supervisor artifact. It does +not pin every file under `src-tauri/` or `scripts/`. If your change touches a +listed authority path, the conformance suite will fail until the lock is +repinned, which is a two-commit process: 1. Commit the functional change on its own. 2. Commit a second change updating the pinned revision, tree, and blob hashes From dc7650428725d64991036c798dc9bc652230a1bc Mon Sep 17 00:00:00 2001 From: Val Alexander Date: Tue, 1 Sep 2026 23:05:08 -0500 Subject: [PATCH 4/4] docs: align governance guidance with current workflow Correct the pinned setup, desktop connection model, branching and release guidance, signing checks, documentation validation, conformance repin process, and conduct reporting path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CODE_OF_CONDUCT.md | 27 +++++++------ CONTRIBUTING.md | 96 ++++++++++++++++++++++++++++------------------ 2 files changed, 74 insertions(+), 49 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index ce194b50..a9710a8c 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -42,12 +42,13 @@ representing the project in public spaces. ## Reporting -Report unacceptable behaviour through one of these channels: +Report unacceptable behaviour to the project maintainers through the +[OpenCoven Discord](https://discord.gg/OpenCoven). Ask for a private channel +with the maintainers and do not post incident details in a public channel. -- Use GitHub's **Report content** control on the specific comment, issue, or - pull request for GitHub-hosted content; or -- Contact the maintainers through the OpenCoven Discord - (https://discord.gg/opencoven) and ask for a private channel. +For GitHub-hosted content, you may also use GitHub's **Report content** control +to alert GitHub to a platform-policy violation. That report goes to GitHub and +does not replace contacting the project maintainers. Security vulnerabilities are handled separately; follow [`SECURITY.md`](SECURITY.md). @@ -56,10 +57,11 @@ Do not post details of an incident publicly before the maintainers have had a chance to respond. All reports are reviewed and investigated promptly and fairly. Maintainers are -obligated to respect the privacy and security of the reporter. Maintainers who -do not follow or enforce this Code of Conduct in good faith may face temporary -or permanent repercussions as determined by other members of the project's -leadership. +obligated to respect the privacy and security of the reporter. A maintainer +named in a report must recuse themselves; another member of the project's +leadership will handle the report. Maintainers who do not follow or enforce +this Code of Conduct in good faith may face temporary or permanent +repercussions as determined by other members of the project's leadership. ## Enforcement @@ -82,6 +84,7 @@ Consequences are proportionate to the impact of the behaviour: ## Attribution This Code of Conduct is adapted from the principles and enforcement structure -of the [Contributor Covenant](https://www.contributor-covenant.org), version -2.1, which is available under the Creative Commons Attribution 4.0 -International license. +of the [Contributor Covenant, version +2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/), which +is available under the [Creative Commons Attribution 4.0 International +license](https://creativecommons.org/licenses/by/4.0/). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a02dfcab..edfb89d6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,30 +19,42 @@ Requirements: - Node.js 24.18.1 (the package engine accepts `>=24.18.0 <25`) - pnpm 10.34.0 via Corepack (`corepack enable`) -- Rust stable toolchain (see [`rust-toolchain.toml`](rust-toolchain.toml)) -- Tauri desktop prerequisites for your platform +- Rust 1.95.0 with `clippy` and `rustfmt` (see + [`rust-toolchain.toml`](rust-toolchain.toml)) +- [Tauri desktop prerequisites](https://v2.tauri.app/start/prerequisites/) for + your platform + +The complete pin list is in +[`docs/developer-toolchains.md`](docs/developer-toolchains.md). ```bash -corepack pnpm install --frozen-lockfile -corepack pnpm dev # web layer only, in a browser -corepack pnpm app:dev # full Tauri desktop shell +corepack enable +pnpm install:clean +pnpm dev # browser fallback and explicit mock routes +pnpm app:dev # production Tauri desktop path ``` -The app runs standalone. A Coven Cave connection is optional and is opted into -from the source bar inside the app. +The browser build cannot connect to Cave. The production desktop path +initializes native identity and manages the Cave connection used for canonical +chat reads. ## Branching and pull requests -`main` is the release branch. Use a short-lived branch and a pull request for -every change: +`main` is the integration branch; release tags are cut only from `main`. Base +every change on current `origin/main`, use a short-lived branch, and open a +pull request: ```bash git worktree add -b / .worktrees/ origin/main cd .worktrees/ ``` -Branch name prefixes: `feat/`, `fix/`, `chore/`, `docs/`, `ci/`, `refactor/`, -`test/`. +Use a descriptive prefix such as `feat/`, `fix/`, `chore/`, `docs/`, `ci/`, +`refactor/`, or `test/`. + +Release preparation is maintainer-owned. Version changes land through a pull +request; maintainers then create a signed, annotated `v*` tag from the merged +commit on `main`. Do not create or move release tags from a topic branch. Pull request expectations: @@ -54,27 +66,25 @@ Pull request expectations: ## Commits must be signed -Every commit must be cryptographically signed and show as **Verified** on -GitHub. Unsigned commits will be rejected. - -```bash -git commit -S -m "feat: short imperative summary" -``` +Project policy requires every commit to be cryptographically signed and to +show as **Verified** on GitHub. Maintainers may ask you to replace unsigned +commits before merging. Confirm your signing configuration before your first commit: ```bash -git config --get user.signingkey # must return a key -git config --get gpg.format # ssh, openpgp, or x509 -git log -1 --show-signature # must report a good signature +git config --get user.signingkey # must identify your signing key +git config --get gpg.format # blank means the OpenPGP default +git commit -S -m "feat: short imperative summary" +git show --show-signature --no-patch HEAD ``` -Commit messages use a `type: summary` first line in the imperative mood, kept -under 72 characters, with detail in the body. +Prefer a `type: summary` first line in the imperative mood, kept under 72 +characters, with detail in the body. ## Verification -Run these before pushing. Pull requests that fail them will not be merged. +For code changes, run the baseline checks before pushing: ```bash corepack pnpm typecheck # TypeScript, no emit @@ -100,13 +110,23 @@ corepack pnpm test:e2e New behaviour needs a test. Bug fixes need a regression test that fails before the fix. +Documentation-only changes do not require the broad code, test, and build +suite. Run `git diff --check`, keep prose wrapped at 100 columns, and verify +new or changed links. The current Biome configuration does not process these +governance documents, so do not report `pnpm lint` as validation for them. + +```bash +git diff --check +``` + ## Code style -Formatting and linting are enforced by [Biome](https://biomejs.dev) — two-space -indentation, 100-column lines, single quotes in TypeScript, double quotes in -JSX. Run `corepack pnpm format` rather than hand-formatting. Do not disable -lint rules with blanket suppressions; a `biome-ignore` must be a single line -directly above the diagnostic and must carry a reason. +Source and configuration formatting and linting are enforced by +[Biome](https://biomejs.dev) — two-space indentation, 100-column lines, single +quotes in TypeScript, double quotes in JSX. Run `corepack pnpm format` rather +than hand-formatting supported files. Do not disable lint rules with blanket +suppressions; a `biome-ignore` must be a single line directly above the +diagnostic and must carry a reason. Comment only what needs clarification. Prefer explicit types at module boundaries and narrow, well-named modules over large ones. @@ -115,18 +135,20 @@ boundaries and narrow, well-named modules over large ones. `phase1-conformance.lock.json` cryptographically pins the Phase 1 authority graph: the Chat, SDK, Cave, Coven, and harness revisions; selected Chat host -files; selected harness scripts and both workflow files +files; selected harness scripts and the two governed workflow files (`.github/workflows/ci.yml` and `.github/workflows/client-v1-conformance.yml`); release and evidence metadata; and the Windows supervisor artifact. It does not pin every file under `src-tauri/` or `scripts/`. If your change touches a -listed authority path, the conformance suite will fail until the lock is -repinned, which is a two-commit process: - -1. Commit the functional change on its own. -2. Commit a second change updating the pinned revision, tree, and blob hashes - to that first commit, plus the byte-count and digest rows in - [`docs/phase1-conformance.md`](docs/phase1-conformance.md) and the - expectations in `src/phase1-conformance-lock.test.ts`. +listed authority path, coordinate with a maintainer before repinning. + +Authority changes normally land in two stages: + +1. Land the functional change without pointing the lock at an unreachable + topic-branch commit. +2. After the canonical merge or squash commit is reachable, land a follow-up + pin that updates the relevant revisions, Git objects, digests, and lock-test + expectations. Documentation byte-count and digest rows change only when + their governed producer bytes change. If you are not sure whether your change is pinned, say so in the pull request and a maintainer will help. Do not repin speculatively.