Skip to content

Commit 3eb3fe3

Browse files
clean6378-max-itclean6378-max-it
authored
docs: contributor onboarding path and CODEOWNERS (#133)
* docs: contributor onboarding path and CODEOWNERS * docs: clarify CODEOWNERS roles and CI gate scope * fix: trim CODEOWNERS reviewers and stabilize search benchmark * Revert changes out of scope of docs * docs: address review feedback * Address Will's feedback
1 parent baee51a commit 3eb3fe3

5 files changed

Lines changed: 146 additions & 2 deletions

File tree

‎.github/CODEOWNERS‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Code owners — auto-requested as reviewers on matching paths.
2+
# Last match wins; see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
3+
#
4+
# Review owners (development + code review): @clean6378-max-it (Chen), @timon0305 (Zilin)
5+
# Both are write collaborators on this repo.
6+
#
7+
# Final approval, merge sequencing, and no-self-merge rules are enforced by branch
8+
# protection / automation, not by listing additional owners here.
9+
10+
* @clean6378-max-it @timon0305

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
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.
44

5+
**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.
6+
57
## Development setup
68

79
### Prerequisites

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,14 +143,16 @@ claude-code-chat-browser/
143143

144144
## Development
145145

146-
See **[`CONTRIBUTING.md`](CONTRIBUTING.md)** for full setup, conventions, and where to change each layer.
146+
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.
147+
148+
Maintainer coverage is concentrated; see [`docs/onboarding.md`](docs/onboarding.md#maintainer-coverage-bus-factor) and [`.github/CODEOWNERS`](.github/CODEOWNERS) for risk and mitigations.
147149

148150
Quick start:
149151

150152
```bash
151153
pip install -r requirements-dev.txt
152154
pytest
153-
npm ci && npm test # only if you changed static/js/
155+
npm ci && npm run test:coverage # only if you changed static/js/
154156
```
155157

156158
`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`).

‎docs/architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,7 @@ No bundler step — modern browsers load modules directly. Frontend unit tests u
152152

153153
## Related documentation
154154

155+
- [Contributor onboarding](onboarding.md)
155156
- [API reference](api-reference.md)
156157
- [Contributing](../CONTRIBUTING.md)
157158
- [README](../README.md)

‎docs/onboarding.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Contributor onboarding
2+
3+
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.
4+
5+
## Before you start
6+
7+
| Doc | What it covers |
8+
|-----|----------------|
9+
| [CONTRIBUTING.md](../CONTRIBUTING.md) | Dev setup, code style, PR checklist, where to change each layer |
10+
| [docs/architecture.md](architecture.md) | Data flow, export state machine, dispatch table, frontend layout |
11+
| [docs/api-reference.md](api-reference.md) | HTTP routes, error codes, field stability |
12+
13+
## Suggested reading order
14+
15+
Work through these in order before touching unfamiliar code:
16+
17+
1. **[docs/architecture.md](architecture.md)** — component diagram, layers, and how JSONL becomes API + UI.
18+
2. **[utils/jsonl_parser.py](../utils/jsonl_parser.py)** — session parsing entry point; tool results flow through `tool_dispatch`.
19+
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).
20+
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).
21+
22+
For API or export changes, also skim [`api/error_codes.py`](../api/error_codes.py) and [`utils/md_exporter.py`](../utils/md_exporter.py).
23+
24+
## First PR walkthrough
25+
26+
### 1. Fork and clone
27+
28+
```bash
29+
# GitHub UI: fork cppalliance/claude-code-chat-browser to your account, then:
30+
git clone https://github.com/<your-user>/claude-code-chat-browser.git
31+
cd claude-code-chat-browser
32+
git remote add upstream https://github.com/cppalliance/claude-code-chat-browser.git
33+
```
34+
35+
### 2. Create a branch
36+
37+
Branch names follow `feat/<topic>`, `fix/<topic>`, `docs/<topic>`, etc. (see [CONTRIBUTING.md](../CONTRIBUTING.md#branching-and-pull-requests)).
38+
39+
```bash
40+
git fetch upstream
41+
git checkout -b docs/my-first-change upstream/master
42+
```
43+
44+
### 3. Development setup
45+
46+
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).
47+
48+
Smoke-test the dev server:
49+
50+
```bash
51+
python app.py --port 5000
52+
# Open http://127.0.0.1:5000
53+
```
54+
55+
### 4. Make a focused change
56+
57+
- One logical change per PR when possible.
58+
- Match existing conventions (ruff, import order, `error_response()` for API errors) — see [Code style](../CONTRIBUTING.md#code-style-and-conventions).
59+
- Add or update tests for behavior changes — see [Tests required](../CONTRIBUTING.md#tests-required-for-common-changes).
60+
61+
### 5. Run the full local gate
62+
63+
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.
64+
65+
```bash
66+
# Lint + format (CI: Ubuntu + Windows + macOS)
67+
ruff check .
68+
ruff format --check .
69+
70+
# Type check (CI: Ubuntu only)
71+
mypy -p api -p utils -p models
72+
73+
# Security audit (production deps)
74+
pip-audit -r requirements.txt
75+
76+
# Python tests (full suite)
77+
pytest -q
78+
79+
# Integration subset (also run in CI)
80+
pytest tests/test_api_integration.py -v
81+
82+
# Frontend — only if you changed static/js/
83+
npm ci
84+
npm run test:coverage
85+
```
86+
87+
Fix formatting with `ruff format .` when `ruff format --check` fails.
88+
89+
### 6. Push and open a PR
90+
91+
```bash
92+
git push -u origin docs/my-first-change
93+
```
94+
95+
Open a pull request against **`master`** on `cppalliance/claude-code-chat-browser`. Include:
96+
97+
- A short summary of **why** the change is needed.
98+
- A **Test plan** checklist (what you ran locally).
99+
- Links to any related issue (`Fixes #NNN` when applicable).
100+
101+
### 7. Review
102+
103+
[`.github/CODEOWNERS`](../.github/CODEOWNERS) auto-requests reviewers on new PRs. **Do not self-merge.**
104+
105+
1. **Code review** from @clean6378-max-it (Chen) or @timon0305 (Zilin). They own development and technical review on this repo.
106+
2. **Final approval and merge** from @wpak-ai (Will Pak) after code review is done.
107+
108+
Address review feedback in follow-up commits on the same branch.
109+
110+
## Good first issues
111+
112+
Browse open issues filtered by label:
113+
114+
- [**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
115+
- [**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
116+
- [**documentation**](https://github.com/cppalliance/claude-code-chat-browser/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation) — docs-only patches
117+
118+
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).
119+
120+
## Maintainer coverage (bus factor)
121+
122+
Recent commit history is concentrated on a small set of identities. If those maintainers are unavailable, review and release can stall.
123+
124+
**Mitigations in this repo:**
125+
126+
- **[`.github/CODEOWNERS`](../.github/CODEOWNERS)** — @clean6378-max-it and @timon0305 for code review routing. Final merge approval (@wpak-ai) is enforced via branch protection.
127+
- **This onboarding path** — lowers the ramp for additional contributors to run gates and ship safely.
128+
129+
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.

0 commit comments

Comments
 (0)