From e5f131799b4f77b0fb004160022b01a336bbcd54 Mon Sep 17 00:00:00 2001 From: chen Date: Tue, 14 Jul 2026 23:49:22 +0800 Subject: [PATCH 1/6] docs: contributor onboarding path and CODEOWNERS --- .github/CODEOWNERS | 16 ++++++ CONTRIBUTING.md | 2 + README.md | 4 +- docs/architecture.md | 1 + docs/onboarding.md | 126 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 .github/CODEOWNERS create mode 100644 docs/onboarding.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..1bc398c --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,16 @@ +# Code owners — auto-requested as reviewers on matching paths. +# Last match wins; see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners +# +# Review expectation: PR authors wait for at least one CODEOWNERS approval before merge. +# Do not self-merge without review, even on docs-only changes. + +# Default owner for the repository. +* @clean6378-max-it + +# Docs and contributor process +/docs/ @clean6378-max-it +/CONTRIBUTING.md @clean6378-max-it +/README.md @clean6378-max-it + +# CI and workflow changes +/.github/ @clean6378-max-it diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a0992c..0464b49 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,8 @@ Thanks for considering a patch. This repo is a small Flask app plus a hash-routed SPA and a CLI export script. Keep changes focused and tested. +**New contributors:** start with [`docs/onboarding.md`](docs/onboarding.md) for a first-PR walkthrough, suggested reading order, full CI gate commands, and good-first-issue pointers. + ## Development setup ### Prerequisites diff --git a/README.md b/README.md index a71b091..9eb9848 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,9 @@ claude-code-chat-browser/ ## Development -See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer. +See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer. New contributors should follow **[`docs/onboarding.md`](docs/onboarding.md)** for a first-PR walkthrough and reading order. + +**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) for review routing and [`docs/onboarding.md`](docs/onboarding.md) so additional contributors can ramp quickly. Quick start: diff --git a/docs/architecture.md b/docs/architecture.md index 4c164a5..5ae0488 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -151,6 +151,7 @@ No bundler step — modern browsers load modules directly. Frontend unit tests u ## Related documentation +- [Contributor onboarding](onboarding.md) - [API reference](api-reference.md) - [Contributing](../CONTRIBUTING.md) - [README](../README.md) diff --git a/docs/onboarding.md b/docs/onboarding.md new file mode 100644 index 0000000..ce8d378 --- /dev/null +++ b/docs/onboarding.md @@ -0,0 +1,126 @@ +# Contributor onboarding + +Welcome. This doc is the **fast path** for your first PR. It links the existing guides rather than repeating them — read it once, then bookmark the references below. + +## Before you start + +| Doc | What it covers | +|-----|----------------| +| [CONTRIBUTING.md](../CONTRIBUTING.md) | Dev setup, code style, PR checklist, where to change each layer | +| [docs/architecture.md](architecture.md) | Data flow, export state machine, dispatch table, frontend layout | +| [docs/api-reference.md](api-reference.md) | HTTP routes, error codes, field stability | + +## Suggested reading order + +Work through these in order before touching unfamiliar code: + +1. **[docs/architecture.md](architecture.md)** — component diagram, layers, and how JSONL becomes API + UI. +2. **[utils/jsonl_parser.py](../utils/jsonl_parser.py)** — session parsing entry point; tool results flow through `tool_dispatch`. +3. **[utils/tool_dispatch.py](../utils/tool_dispatch.py)** — priority-based `_TOOL_RESULT_DISPATCH` table; read the module docstring and [dispatch table notes](architecture.md#dispatch-table). +4. **Frontend SPA** — [`static/js/app.js`](../static/js/app.js) (routing), [`static/js/sessions.js`](../static/js/sessions.js) (message panel), [`static/js/render/registry.js`](../static/js/render/registry.js) (tool renderers). + +For API or export changes, also skim [`api/error_codes.py`](../api/error_codes.py) and [`utils/md_exporter.py`](../utils/md_exporter.py). + +## First PR walkthrough + +### 1. Fork and clone + +```powershell +# GitHub UI: fork cppalliance/claude-code-chat-browser to your account, then: +git clone https://github.com//claude-code-chat-browser.git +cd claude-code-chat-browser +git remote add upstream https://github.com/cppalliance/claude-code-chat-browser.git +``` + +On macOS/Linux, use the same `git clone` / `git remote add` commands in your shell. + +### 2. Create a branch + +Branch names follow `feat/`, `fix/`, `docs/`, etc. (see [CONTRIBUTING.md](../CONTRIBUTING.md#branching-and-pull-requests)). + +```bash +git fetch upstream +git checkout -b docs/my-first-change upstream/master +``` + +### 3. Development setup + +Follow **[CONTRIBUTING.md — Development setup](../CONTRIBUTING.md#development-setup)** for your OS (Python 3.12 venv, `pip install -r requirements-dev.txt`, optional Node 20+ for JS). + +Smoke-test the dev server: + +```bash +python app.py --port 5000 +# Open http://127.0.0.1:5000 +``` + +### 4. Make a focused change + +- One logical change per PR when possible. +- Match existing conventions (ruff, import order, `error_response()` for API errors) — see [Code style](../CONTRIBUTING.md#code-style-and-conventions). +- Add or update tests for behavior changes — see [Tests required](../CONTRIBUTING.md#tests-required-for-common-changes). + +### 5. Run the full local gate + +CI runs these on Ubuntu, Windows, and macOS. Run them locally before opening a PR: + +```bash +# Lint + format (required) +ruff check . +ruff format --check . + +# Type check (Ubuntu CI job; run locally before Python-heavy changes) +mypy -p api -p utils -p models -p scripts + +# Security audit (production deps) +pip-audit -r requirements.txt + +# Python tests (full suite) +pytest -q + +# Integration subset (also run in CI) +pytest tests/test_api_integration.py -v + +# Frontend — only if you changed static/js/ +npm ci +npm test +``` + +Fix formatting with `ruff format .` when `ruff format --check` fails. + +### 6. Push and open a PR + +```bash +git push -u origin docs/my-first-change +``` + +Open a pull request against **`master`** on `cppalliance/claude-code-chat-browser`. Include: + +- A short summary of **why** the change is needed. +- A **Test plan** checklist (what you ran locally). +- Links to any related issue (`Fixes #NNN` when applicable). + +### 7. Review + +[`.github/CODEOWNERS`](../.github/CODEOWNERS) auto-requests reviewers on new PRs. **Do not self-merge** — wait for at least one approval. Address review feedback in follow-up commits on the same branch. + +## Good first issues + +Browse open issues filtered by label: + +- [**good first issue**](https://github.com/cppalliance/claude-code-chat-browser/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — scoped for newcomers +- [**help wanted**](https://github.com/cppalliance/claude-code-chat-browser/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) — maintainers welcome extra hands +- [**documentation**](https://github.com/cppalliance/claude-code-chat-browser/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation) — docs-only patches + +Not sure which issue to pick? Comment on an issue or open a draft PR early for CI feedback — see [Getting help](../CONTRIBUTING.md#getting-help). + +## Maintainer coverage (bus factor) + +Recent commit history is concentrated on a small set of identities. If those maintainers are unavailable, review and release can stall. + +**Mitigations in this repo:** + +- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — routes review requests so PRs do not rely on ad-hoc pings. +- **This onboarding path** — lowers the ramp for a second reviewer or contributor to run gates and ship safely. + +If you are joining as a reviewer, read the [suggested reading order](#suggested-reading-order) and run the [full local gate](#5-run-the-full-local-gate) once on `master` before approving your first PR. From ac2c4c0dd7b9c203ff239606af48b581649bcf72 Mon Sep 17 00:00:00 2001 From: chen Date: Wed, 15 Jul 2026 00:09:33 +0800 Subject: [PATCH 2/6] docs: clarify CODEOWNERS roles and CI gate scope --- .github/CODEOWNERS | 20 ++++++++++++-------- README.md | 2 +- docs/onboarding.md | 17 +++++++++++------ 3 files changed, 24 insertions(+), 15 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 1bc398c..8c85ca3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,16 +1,20 @@ # Code owners — auto-requested as reviewers on matching paths. # Last match wins; see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners # -# Review expectation: PR authors wait for at least one CODEOWNERS approval before merge. -# Do not self-merge without review, even on docs-only changes. +# Roles: +# Development + code review: @clean6378-max-it (Chen), @timon0305 (Zilin) +# Final approval + merge: @wpak-ai (Will Pak) +# +# PR authors do not self-merge. Get a code review from Chen or Zilin, then final +# approval from Will before merge. -# Default owner for the repository. -* @clean6378-max-it +# Default owners for the repository. +* @clean6378-max-it @timon0305 @wpak-ai # Docs and contributor process -/docs/ @clean6378-max-it -/CONTRIBUTING.md @clean6378-max-it -/README.md @clean6378-max-it +/docs/ @clean6378-max-it @timon0305 @wpak-ai +/CONTRIBUTING.md @clean6378-max-it @timon0305 @wpak-ai +/README.md @clean6378-max-it @timon0305 @wpak-ai # CI and workflow changes -/.github/ @clean6378-max-it +/.github/ @clean6378-max-it @timon0305 @wpak-ai diff --git a/README.md b/README.md index 9eb9848..28375dd 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ claude-code-chat-browser/ See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer. New contributors should follow **[`docs/onboarding.md`](docs/onboarding.md)** for a first-PR walkthrough and reading order. -**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) for review routing and [`docs/onboarding.md`](docs/onboarding.md) so additional contributors can ramp quickly. +**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) splits development/code review (@clean6378-max-it, @timon0305) from final approval and merge (@wpak-ai), plus [`docs/onboarding.md`](docs/onboarding.md) for contributor ramp-up. Quick start: diff --git a/docs/onboarding.md b/docs/onboarding.md index ce8d378..906f525 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -62,14 +62,14 @@ python app.py --port 5000 ### 5. Run the full local gate -CI runs these on Ubuntu, Windows, and macOS. Run them locally before opening a PR: +Run these locally before opening a PR. In CI, **ruff** (`check` + `format --check`) runs on Ubuntu, Windows, and macOS. **mypy** runs only in the Ubuntu job; run it locally before Python-heavy changes. **pip-audit**, **pytest**, integration tests, and **Vitest** also run on all three platforms in CI. ```bash -# Lint + format (required) +# Lint + format (CI: Ubuntu + Windows + macOS) ruff check . ruff format --check . -# Type check (Ubuntu CI job; run locally before Python-heavy changes) +# Type check (CI: Ubuntu only) mypy -p api -p utils -p models -p scripts # Security audit (production deps) @@ -102,7 +102,12 @@ Open a pull request against **`master`** on `cppalliance/claude-code-chat-browse ### 7. Review -[`.github/CODEOWNERS`](../.github/CODEOWNERS) auto-requests reviewers on new PRs. **Do not self-merge** — wait for at least one approval. Address review feedback in follow-up commits on the same branch. +[`.github/CODEOWNERS`](../.github/CODEOWNERS) auto-requests reviewers on new PRs. **Do not self-merge.** + +1. **Code review** from @clean6378-max-it (Chen) or @timon0305 (Zilin). They own development and technical review on this repo. +2. **Final approval and merge** from @wpak-ai (Will Pak) after code review is done. + +Address review feedback in follow-up commits on the same branch. ## Good first issues @@ -120,7 +125,7 @@ Recent commit history is concentrated on a small set of identities. If those mai **Mitigations in this repo:** -- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — routes review requests so PRs do not rely on ad-hoc pings. -- **This onboarding path** — lowers the ramp for a second reviewer or contributor to run gates and ship safely. +- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — @clean6378-max-it and @timon0305 for development and code review; @wpak-ai for final approval and merge. +- **This onboarding path** — lowers the ramp for additional contributors to run gates and ship safely. If you are joining as a reviewer, read the [suggested reading order](#suggested-reading-order) and run the [full local gate](#5-run-the-full-local-gate) once on `master` before approving your first PR. From a3a1e06edbfb2388d11a9efc2c5e39d090abc7ea Mon Sep 17 00:00:00 2001 From: chen Date: Wed, 15 Jul 2026 00:26:43 +0800 Subject: [PATCH 3/6] fix: trim CODEOWNERS reviewers and stabilize search benchmark --- .github/CODEOWNERS | 18 ++++++++---------- README.md | 2 +- docs/onboarding.md | 2 +- tests/benchmarks/conftest.py | 14 +++++++++----- 4 files changed, 19 insertions(+), 17 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 8c85ca3..7d57f77 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,20 +1,18 @@ # Code owners — auto-requested as reviewers on matching paths. # Last match wins; see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners # -# Roles: -# Development + code review: @clean6378-max-it (Chen), @timon0305 (Zilin) -# Final approval + merge: @wpak-ai (Will Pak) +# Review owners (development + code review): @clean6378-max-it (Chen), @timon0305 (Zilin) # -# PR authors do not self-merge. Get a code review from Chen or Zilin, then final -# approval from Will before merge. +# Final approval, merge sequencing, and no-self-merge rules are enforced by branch +# protection / automation, not by listing additional owners here. # Default owners for the repository. -* @clean6378-max-it @timon0305 @wpak-ai +* @clean6378-max-it @timon0305 # Docs and contributor process -/docs/ @clean6378-max-it @timon0305 @wpak-ai -/CONTRIBUTING.md @clean6378-max-it @timon0305 @wpak-ai -/README.md @clean6378-max-it @timon0305 @wpak-ai +/docs/ @clean6378-max-it @timon0305 +/CONTRIBUTING.md @clean6378-max-it @timon0305 +/README.md @clean6378-max-it @timon0305 # CI and workflow changes -/.github/ @clean6378-max-it @timon0305 @wpak-ai +/.github/ @clean6378-max-it @timon0305 diff --git a/README.md b/README.md index 28375dd..ee621e7 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,7 @@ claude-code-chat-browser/ See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer. New contributors should follow **[`docs/onboarding.md`](docs/onboarding.md)** for a first-PR walkthrough and reading order. -**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) splits development/code review (@clean6378-max-it, @timon0305) from final approval and merge (@wpak-ai), plus [`docs/onboarding.md`](docs/onboarding.md) for contributor ramp-up. +**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) routes code review to @clean6378-max-it and @timon0305; final merge approval (@wpak-ai) is enforced via branch protection, plus [`docs/onboarding.md`](docs/onboarding.md) for contributor ramp-up. Quick start: diff --git a/docs/onboarding.md b/docs/onboarding.md index 906f525..e09f3d1 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -125,7 +125,7 @@ Recent commit history is concentrated on a small set of identities. If those mai **Mitigations in this repo:** -- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — @clean6378-max-it and @timon0305 for development and code review; @wpak-ai for final approval and merge. +- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — @clean6378-max-it and @timon0305 for code review routing. Final merge approval (@wpak-ai) is enforced via branch protection. - **This onboarding path** — lowers the ramp for additional contributors to run gates and ship safely. If you are joining as a reviewer, read the [suggested reading order](#suggested-reading-order) and run the [full local gate](#5-run-the-full-local-gate) once on `master` before approving your first PR. diff --git a/tests/benchmarks/conftest.py b/tests/benchmarks/conftest.py index 2b22088..1369773 100644 --- a/tests/benchmarks/conftest.py +++ b/tests/benchmarks/conftest.py @@ -51,13 +51,14 @@ def tracemalloc_peak() -> TracemallocPeak: def write_jsonl(path: Path, line_count: int, *, first_timestamp: str | None = None) -> Path: """Write a JSONL session file with *line_count* rows derived from the template fixture.""" template = json.loads(TEMPLATE_LINE) + if first_timestamp is not None: + base_dt = datetime.fromisoformat(first_timestamp.replace("Z", "+00:00")) + else: + base_dt = _EXPORT_SESSION_BASE.replace(hour=10) with path.open("w", encoding="utf-8") as f: for i in range(line_count): entry = deepcopy(template) - if i == 0 and first_timestamp is not None: - entry["timestamp"] = first_timestamp - else: - entry["timestamp"] = f"2026-06-12T10:{i % 60:02d}:00Z" + entry["timestamp"] = (base_dt + timedelta(minutes=i)).strftime("%Y-%m-%dT%H:%M:%SZ") if i % 3 == 1: msg = entry.setdefault("message", {}) if isinstance(msg, dict) and "content" in msg: @@ -79,8 +80,11 @@ def seed_search_corpus( """Create a multi-session project tree under *base_dir* for search benchmarks.""" project = base_dir / "bench-project" project.mkdir(parents=True, exist_ok=True) + # Keep every message inside the default 30-day search window (see DEFAULT_SEARCH_WINDOW_DAYS). + anchor = datetime.now(UTC) - timedelta(days=1) for i in range(session_count): - write_jsonl(project / f"session_{i:04d}.jsonl", lines_per_session) + first_ts = (anchor + timedelta(minutes=i * 30)).strftime("%Y-%m-%dT%H:%M:%SZ") + write_jsonl(project / f"session_{i:04d}.jsonl", lines_per_session, first_timestamp=first_ts) return base_dir From 2619b9ff978bbd73bebf6925957e0373a5cf0eac Mon Sep 17 00:00:00 2001 From: star-med Date: Wed, 15 Jul 2026 02:52:13 +0800 Subject: [PATCH 4/6] Revert changes out of scope of docs --- tests/benchmarks/conftest.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/tests/benchmarks/conftest.py b/tests/benchmarks/conftest.py index 1369773..2b22088 100644 --- a/tests/benchmarks/conftest.py +++ b/tests/benchmarks/conftest.py @@ -51,14 +51,13 @@ def tracemalloc_peak() -> TracemallocPeak: def write_jsonl(path: Path, line_count: int, *, first_timestamp: str | None = None) -> Path: """Write a JSONL session file with *line_count* rows derived from the template fixture.""" template = json.loads(TEMPLATE_LINE) - if first_timestamp is not None: - base_dt = datetime.fromisoformat(first_timestamp.replace("Z", "+00:00")) - else: - base_dt = _EXPORT_SESSION_BASE.replace(hour=10) with path.open("w", encoding="utf-8") as f: for i in range(line_count): entry = deepcopy(template) - entry["timestamp"] = (base_dt + timedelta(minutes=i)).strftime("%Y-%m-%dT%H:%M:%SZ") + if i == 0 and first_timestamp is not None: + entry["timestamp"] = first_timestamp + else: + entry["timestamp"] = f"2026-06-12T10:{i % 60:02d}:00Z" if i % 3 == 1: msg = entry.setdefault("message", {}) if isinstance(msg, dict) and "content" in msg: @@ -80,11 +79,8 @@ def seed_search_corpus( """Create a multi-session project tree under *base_dir* for search benchmarks.""" project = base_dir / "bench-project" project.mkdir(parents=True, exist_ok=True) - # Keep every message inside the default 30-day search window (see DEFAULT_SEARCH_WINDOW_DAYS). - anchor = datetime.now(UTC) - timedelta(days=1) for i in range(session_count): - first_ts = (anchor + timedelta(minutes=i * 30)).strftime("%Y-%m-%dT%H:%M:%SZ") - write_jsonl(project / f"session_{i:04d}.jsonl", lines_per_session, first_timestamp=first_ts) + write_jsonl(project / f"session_{i:04d}.jsonl", lines_per_session) return base_dir From 3fe0de43d154843ca4722addce6272b6b4f66f05 Mon Sep 17 00:00:00 2001 From: star-med Date: Wed, 15 Jul 2026 03:03:37 +0800 Subject: [PATCH 5/6] docs: address review feedback --- .github/CODEOWNERS | 10 +--------- README.md | 2 -- docs/onboarding.md | 4 +--- 3 files changed, 2 insertions(+), 14 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7d57f77..b56ea83 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -2,17 +2,9 @@ # Last match wins; see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners # # Review owners (development + code review): @clean6378-max-it (Chen), @timon0305 (Zilin) +# Both are write collaborators on this repo. # # Final approval, merge sequencing, and no-self-merge rules are enforced by branch # protection / automation, not by listing additional owners here. -# Default owners for the repository. * @clean6378-max-it @timon0305 - -# Docs and contributor process -/docs/ @clean6378-max-it @timon0305 -/CONTRIBUTING.md @clean6378-max-it @timon0305 -/README.md @clean6378-max-it @timon0305 - -# CI and workflow changes -/.github/ @clean6378-max-it @timon0305 diff --git a/README.md b/README.md index ee621e7..5f6337d 100644 --- a/README.md +++ b/README.md @@ -145,8 +145,6 @@ claude-code-chat-browser/ See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer. New contributors should follow **[`docs/onboarding.md`](docs/onboarding.md)** for a first-PR walkthrough and reading order. -**Maintainer coverage:** commit activity is currently concentrated on a small set of identities (bus-factor risk). Mitigations: [`.github/CODEOWNERS`](.github/CODEOWNERS) routes code review to @clean6378-max-it and @timon0305; final merge approval (@wpak-ai) is enforced via branch protection, plus [`docs/onboarding.md`](docs/onboarding.md) for contributor ramp-up. - Quick start: ```bash diff --git a/docs/onboarding.md b/docs/onboarding.md index e09f3d1..928827d 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -25,15 +25,13 @@ For API or export changes, also skim [`api/error_codes.py`](../api/error_codes.p ### 1. Fork and clone -```powershell +```bash # GitHub UI: fork cppalliance/claude-code-chat-browser to your account, then: git clone https://github.com//claude-code-chat-browser.git cd claude-code-chat-browser git remote add upstream https://github.com/cppalliance/claude-code-chat-browser.git ``` -On macOS/Linux, use the same `git clone` / `git remote add` commands in your shell. - ### 2. Create a branch Branch names follow `feat/`, `fix/`, `docs/`, etc. (see [CONTRIBUTING.md](../CONTRIBUTING.md#branching-and-pull-requests)). From 60d92f4fdf627a1918f3591ef8943a1ad8aaa0f5 Mon Sep 17 00:00:00 2001 From: chen Date: Wed, 15 Jul 2026 07:35:01 +0800 Subject: [PATCH 6/6] Address Will's feedback --- README.md | 4 +++- docs/onboarding.md | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5f6337d..99b0007 100644 --- a/README.md +++ b/README.md @@ -145,12 +145,14 @@ claude-code-chat-browser/ See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer. New contributors should follow **[`docs/onboarding.md`](docs/onboarding.md)** for a first-PR walkthrough and reading order. +Maintainer coverage is concentrated; see [`docs/onboarding.md`](docs/onboarding.md#maintainer-coverage-bus-factor) and [`.github/CODEOWNERS`](.github/CODEOWNERS) for risk and mitigations. + Quick start: ```bash pip install -r requirements-dev.txt pytest -npm ci && npm test # only if you changed static/js/ +npm ci && npm run test:coverage # only if you changed static/js/ ``` `requirements.txt` carries only the runtime dep (Flask); `requirements-dev.txt` pulls it in via `-r` and adds pytest (+ coverage). Frontend tests use vitest (`package.json`). diff --git a/docs/onboarding.md b/docs/onboarding.md index 928827d..4669db4 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -68,7 +68,7 @@ ruff check . ruff format --check . # Type check (CI: Ubuntu only) -mypy -p api -p utils -p models -p scripts +mypy -p api -p utils -p models # Security audit (production deps) pip-audit -r requirements.txt @@ -81,7 +81,7 @@ pytest tests/test_api_integration.py -v # Frontend — only if you changed static/js/ npm ci -npm test +npm run test:coverage ``` Fix formatting with `ruff format .` when `ruff format --check` fails.