Contributing to tcm-ts — tcm-ts

Contributing to tcm-ts

tcm is developed in tcm. All its code is in its own codebase, on tcm's server; the git repository only says how to get it. So a change isn't a pull request: it's a contribution, a branch of the codebase proposed on tcm's server and reviewed there as definitions, as on Unison Share. Anyone can read tcm's codebase; proposing a change takes a contributor's token.

Only want to use tcm? Install it and follow your first codebase.

Setting up

You need Node 22.18 or newer, pnpm and git. Tests that render in a browser need Chrome (they're skipped without it).

git clone https://github.com/hipstersmoothie/tcm-ts && cd tcm-ts
pnpm tcm status

The first pnpm tcm installs the tcm that tcm's server runs (into dist/known-good) and pulls tcm's codebase, history and all (into codebase/, which git ignores). Reading needs no token. Developing tcm-ts says how the codebase is laid out and how it's tested.

To propose changes, ask the maintainer for a contributor's token (they make one with tcm user add <your handle>). Then:

pnpm tcm remote add origin https://tcm.codes --token <your token>
pnpm tcm user                     # you're @<handle> on origin

Making a change

  • With an agent: open the repository in Claude Code or another MCP client. Its .mcp.json runs tcm's MCP server on the codebase, and AGENTS.md has the rules. Each agent works in a session, a branch of its own, which tcm_status names.
  • By hand: make a branch (pnpm tcm branch my-change && pnpm tcm switch my-change), then change code with pnpm tcm patch, or pnpm tcm edit and pnpm tcm update (scratch files).

A change needs:

  • One thing. Each change is one history entry, and says what it does and why.
  • Tests. New behaviour gets a test definition (export const testX = () => …), beside the code, or in tcmts.cli.test.e2e if it runs tcm as a program (testing).
  • Docs. A change to what users see (a command, flag, API, error they act on, or limit) updates its page in tcmts.docs. New commands and flags also go in tcmts.docs.cli and tcmts.cli.commands; limits in tcmts.docs.limitations.
  • Pinned hashes unchanged, unless you're changing the hash format on purpose.
  • pnpm verify passing on its branch: TCM_BRANCH=<branch> pnpm verify.

Proposing it

From your branch:

pnpm tcm contribute --title "What it does" --description "Why"

For an agent's session: TCM_BRANCH=<its branch> pnpm tcm contribute --as my-change --title "…". This pushes the branch as @<handle>/my-change, opens a contribution of it into main, and prints its review page. Agents don't push or contribute on their own: you do, or tell one to.

  • To update it, push again from the same branch: pnpm tcm contribute or pnpm tcm push.
  • Review happens in the terminal (pnpm tcm contribution view <id>, pnpm tcm contribution comment <id> "…") or on the review page.
  • If it conflicts with main, bring main into your branch (pnpm tcm pull origin main), settle the conflicts (pnpm tcm todo), and push again (merging).
  • The maintainer merges it. Then pnpm tcm switch main && pnpm tcm pull brings it back.

Built from c482a14e