Contributing to tcm-ts — tcm-ts

41. Contributing to tcm-ts

tcm is developed in tcm: all of it is in its own codebase, on tcm's server, and 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.

41.1 Setting up

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

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

The first pnpm tcm gets the tcm tcm's server runs (into dist/known-good) and tcm's codebase, history and all (into codebase/, which git ignores). Reading needs no token: tcm's server is public. pnpm test runs the tests a change reaches, and pnpm verify checks everything (the first time takes some minutes; after that, only what a change reaches runs again). 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

41.2 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).

What a change needs, as AGENTS.md says:

  • One thing. Each change is one entry in the history, 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 when it runs tcm as a program (testing).
  • Docs. A change to what users see (a command, a flag, an API, an error they act on, a limit) updates its page in tcmts.docs with it: new commands and flags in tcmts.docs.cli and tcmts.cli.commands too, limits in tcmts.docs.limitations.
  • Pinned hashes stay as they are, unless the change is to the hash format, on purpose.
  • pnpm verify passes on its branch: TCM_BRANCH=<branch> pnpm verify.

41.3 Proposing it

From your branch:

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

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

  • Pushing again updates it: pnpm tcm contribute, or pnpm tcm push, from the same branch.
  • Review is 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