From e490c9d890be8f69d6019259523756d0dfc9118b Mon Sep 17 00:00:00 2001 From: jimpablo <194239734+jimpablo@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:47:28 +0800 Subject: [PATCH 1/2] docs: require origin/main worktrees and hub-repo dogfood CONTRIBUTING no longer branches from master. Contributors build, link, and init/pull the public teamai-hub team repo from the CLI clone. Closes #479. --- .github/CONTRIBUTING.md | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 99aa2712..f4c0aed5 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -10,6 +10,8 @@ cd teamai-cli npm install ``` +If you forked first, clone your fork and add `https://github.com/Tencent/teamai-cli.git` as `upstream` so you can branch from its `main`. + ### Common commands ```bash @@ -20,13 +22,31 @@ npx vitest run --coverage npm run test:e2e # E2E tests (optional, requires a live test repo) ``` -### Running your local build +### Running your local build (required dogfood) + +Work in the **CLI clone**. Do **not** run `teamai init .` here — that is single-repo mode and turns this source tree into the team repo (easy to commit by mistake). ```bash -npm link +npm run build && npm link teamai --version +teamai init https://github.com/teamai-hub/teamai-cli-dev --scope project --role dev +teamai pull +git status # nothing under .teamai/ or tool dirs should be staged for this repo ``` +Init the **canonical hub URL** above, not a personal fork. `teamai init ` treats that URL as the team repo; a fork diverges immediately, and GitHub push/PR today targets the configured remote (no fork-to-upstream flow). + +`Push failed (you can push manually later)` on member registration is **expected** without write access. Local config is still saved; `teamai pull` still works. + +`git status` after init/pull must not imply committing TeamAI local files into `teamai-cli`. Leave untracked or ignored `.teamai/` directories and AI tool dirs (for example `.claude/`, `.codebuddy/`, `.codex/`, `.cursor/`, `.opencode/`) out of your commits. + +The public team repo is read-only for most contributors. `digest` / `dashboard` read `stats/`, `sessions/`, and `members/` from that repo; those files are written via git, so **no write ⇒ not in team stats**. Maintainers do not grant write access to every internet contributor. + +| Who | Hub repo access | Required setup | In team digest | +| --- | --- | --- | --- | +| Contributors | read | `init` + `pull` | no | +| Collaborators (after a few PRs) | write, `main` protected | full, including reports | yes | + ## Project Layout ``` @@ -43,7 +63,14 @@ See [docs/providers.md](../docs/providers.md) for how to add a new git provider. ## Making a Change -1. Fork the repo and create a feature branch from `master`. +1. Fork the repo and create a feature branch from the latest `origin/main` (fetch `https://github.com/Tencent/teamai-cli.git` first if your `origin` is a fork). Prefer a git worktree so the main checkout stays clean: + + ```bash + git fetch origin + git worktree add -b my-feature .worktrees/my-feature origin/main + cd .worktrees/my-feature + ``` + 2. Write tests for your change (we target 80%+ coverage). 3. Run `npx vitest run` and `npx tsc --noEmit` — both must pass. 4. Use conventional commits where possible: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`. From c600717047f32023f66968c1c7bbf5a4b7c9fd16 Mon Sep 17 00:00:00 2001 From: jimpablo <194239734+jimpablo@users.noreply.github.com> Date: Thu, 10 Sep 2026 13:57:49 +0800 Subject: [PATCH 2/2] docs: keep CONTRIBUTING #479 changes to the requested minimum Drop extra fork/upstream and worktree tutorials. Keep the original section layout; add only the issue's dogfood sequence, pitfalls, and access table, and switch the branch baseline to origin/main. --- .github/CONTRIBUTING.md | 28 ++++++++++------------------ 1 file changed, 10 insertions(+), 18 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index f4c0aed5..f1aa3ead 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -10,8 +10,6 @@ cd teamai-cli npm install ``` -If you forked first, clone your fork and add `https://github.com/Tencent/teamai-cli.git` as `upstream` so you can branch from its `main`. - ### Common commands ```bash @@ -22,31 +20,32 @@ npx vitest run --coverage npm run test:e2e # E2E tests (optional, requires a live test repo) ``` -### Running your local build (required dogfood) +### Running your local build -Work in the **CLI clone**. Do **not** run `teamai init .` here — that is single-repo mode and turns this source tree into the team repo (easy to commit by mistake). +Work in the **CLI clone**, not as `teamai init .`. ```bash npm run build && npm link -teamai --version teamai init https://github.com/teamai-hub/teamai-cli-dev --scope project --role dev teamai pull git status # nothing under .teamai/ or tool dirs should be staged for this repo ``` -Init the **canonical hub URL** above, not a personal fork. `teamai init ` treats that URL as the team repo; a fork diverges immediately, and GitHub push/PR today targets the configured remote (no fork-to-upstream flow). - -`Push failed (you can push manually later)` on member registration is **expected** without write access. Local config is still saved; `teamai pull` still works. +Documented pitfalls: -`git status` after init/pull must not imply committing TeamAI local files into `teamai-cli`. Leave untracked or ignored `.teamai/` directories and AI tool dirs (for example `.claude/`, `.codebuddy/`, `.codex/`, `.cursor/`, `.opencode/`) out of your commits. +- Init the **canonical hub URL**, not a personal fork. `teamai init ` treats that URL as the team repo; a fork diverges immediately, and GitHub push/PR today targets the configured remote (no fork-to-upstream flow). +- Do **not** run `teamai init .`. That is single-repo mode: it turns the CLI source tree into the team repo and writes scaffolding at the repo root (easy to commit by mistake). +- `Push failed (you can push manually later)` on member registration is **expected** without write access. Local config is still saved; `teamai pull` still works. -The public team repo is read-only for most contributors. `digest` / `dashboard` read `stats/`, `sessions/`, and `members/` from that repo; those files are written via git, so **no write ⇒ not in team stats**. Maintainers do not grant write access to every internet contributor. +`digest` / `dashboard` read `stats/`, `sessions/`, and `members/` from the team repo. Those files are written via git, so **no write ⇒ not in team stats**. Giving every internet contributor write on the hub repo is not acceptable. | Who | Hub repo access | Required setup | In team digest | | --- | --- | --- | --- | | Contributors | read | `init` + `pull` | no | | Collaborators (after a few PRs) | write, `main` protected | full, including reports | yes | +`git status` after init does not imply committing TeamAI local files into `teamai-cli`. Do not stage `.teamai/` or tool dirs. + ## Project Layout ``` @@ -63,14 +62,7 @@ See [docs/providers.md](../docs/providers.md) for how to add a new git provider. ## Making a Change -1. Fork the repo and create a feature branch from the latest `origin/main` (fetch `https://github.com/Tencent/teamai-cli.git` first if your `origin` is a fork). Prefer a git worktree so the main checkout stays clean: - - ```bash - git fetch origin - git worktree add -b my-feature .worktrees/my-feature origin/main - cd .worktrees/my-feature - ``` - +1. Fork the repo and create a feature branch from the latest `origin/main`. Prefer a git worktree for code changes. 2. Write tests for your change (we target 80%+ coverage). 3. Run `npx vitest run` and `npx tsc --noEmit` — both must pass. 4. Use conventional commits where possible: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`.