Tencent / Tencent/teamai-cli

docs: fix CONTRIBUTING branch baseline and require dogfooding the public team repo

Open Beginner friendly
#479 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
4.8k
Forks
342
Avg merge
13h 48m
Merged PRs (30d)
211

Description

Summary

.github/CONTRIBUTING.md is wrong on the default branch, and it never asks CLI contributors to run TeamAI against a TeamAI team repo (dogfooding / bootstrap).

Problems

  1. Wrong branch. "Making a Change" tells people to create a feature branch from master. The default branch of this repo is main (origin/HEADrefs/heads/main).
  2. No dogfood setup. Contributors only npm install / npm link. They never teamai init a team repo, so they do not exercise pull, hooks, recall, or the contributor path while developing the CLI.

Proposed docs-only change

Update .github/CONTRIBUTING.md only (README already links there). No new CLI commands.

Branch baseline
  • Create feature branches from the latest origin/main.
  • Prefer a git worktree for code changes, matching existing maintainer practice.
Required dogfood (all contributors)

Create a regular (not template) public team repo under teamai-hub, e.g. https://github.com/teamai-hub/teamai-cli-dev, with main branch protection (PR + review). Put only public-safe skills / rules / docs there.

In the CLI clone (not as teamai init .):

npm run build && npm link
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

Document these pitfalls:

  • Init the canonical hub URL, not a personal fork. teamai init <url> 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.
Write access and stats (do not grant write to every 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.

Document the split:

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

Do not document an internal / TGit contributor path in this public guide.

Out of scope

  • CLI behavior changes (including fork-aware teamai push).
  • HTTP report/sync/ack so read-only users appear in digest.
  • Sweeping leftover master wording in other files (providers.md, comments, skills).

Acceptance

  • CONTRIBUTING never says to branch from master.
  • A contributor can complete build → link → init hub repo → pull, and understands a failed member push as normal.
  • git status after init does not imply committing TeamAI local files into teamai-cli.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read .github/CONTRIBUTING.md and compare its branch instructions with the issue’s required build, link, init, and pull flow. Update that file only so it uses origin/main, explains public team-repo dogfooding, access limitations, and expected push failures. Verify the documented acceptance points, including a clean git status after initialization.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, github
Domain
cli, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
86/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.