Skip to content

Commit 5a8765e

Browse files
Nick Ficanoclaude
Nick Ficano
and
claude
committed
docs: add CONTRIBUTING.md from shared SDK template
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent c76fe6e commit 5a8765e

1 file changed

Lines changed: 151 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Contributing to @agentruntimecontrolprotocol/sdk
2+
3+
Thanks for your interest in improving the TypeScript SDK for ARCP. This
4+
document covers how to report issues, propose changes, and get a change merged.
5+
6+
By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).
7+
8+
## Where changes belong
9+
10+
ARCP is two things in two places, and a change belongs to exactly one of them:
11+
12+
- **The protocol** — the wire format, message semantics, lease rules, error
13+
taxonomy, feature flags. These live in the
14+
[specification repository](https://github.com/agentruntimecontrolprotocol/spec).
15+
If your idea changes what goes *on the wire* or what a conformant runtime must
16+
do, it is a spec change — open it there, not here. This SDK implements the
17+
spec; it does not define it.
18+
- **This SDK** — how the protocol is expressed idiomatically in TypeScript:
19+
bugs, ergonomics, performance, missing-but-specified features, docs, tests.
20+
Those belong here.
21+
22+
When in doubt, open an issue here and we'll redirect if it's really a protocol
23+
question.
24+
25+
## The golden rule: conform, don't extend
26+
27+
A change to this SDK must keep it a faithful client of
28+
[ARCP v1.1 (draft)](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
29+
Concretely:
30+
31+
- **Don't invent wire behavior.** No envelope fields, event kinds, error codes,
32+
or feature flags that the spec doesn't define. If you need one, it's a spec
33+
proposal first.
34+
- **Negotiate honestly.** Only advertise a feature flag in `session.hello` once
35+
the SDK actually implements it. The feature matrix in the README must match
36+
what the code negotiates — a row marked `Supported` is a promise.
37+
- **Respect the semantics.** Sequence numbers stay gap-free and monotonic;
38+
`LEASE_EXPIRED` and `BUDGET_EXHAUSTED` stay non-retryable; the effective
39+
feature set is the intersection of client and runtime advertisements. Tests
40+
must not paper over a semantic the spec requires.
41+
- **Stay layered.** This SDK controls runtimes. It does not expose tools (that's
42+
MCP) or export telemetry (that's OpenTelemetry). PRs that blur those layers
43+
will be asked to move the logic out.
44+
45+
## Reporting bugs
46+
47+
Open an issue with: the SDK version and TypeScript version, the runtime you
48+
connected to, a minimal reproduction (the smallest program that triggers it),
49+
what you expected, and what happened. A failing test is the best possible bug
50+
report. Wire-level traces (the envelopes exchanged) help enormously for protocol
51+
behavior — redact any `auth.token` or provisioned-credential `value` first.
52+
53+
## Proposing a change
54+
55+
For anything beyond a small fix, open an issue describing the problem before
56+
writing code, so we can agree on the approach. Small, focused PRs review faster
57+
than large ones; if a change is big, say so early and we'll help break it down.
58+
59+
## Development setup
60+
61+
This repo is a pnpm workspace containing the `@agentruntimecontrolprotocol/*`
62+
packages (`core`, `client`, `runtime`, `sdk`, and the `middleware/*` adapters).
63+
You need Node.js `>= 22` and `pnpm` 9.15.0 (the version pinned via
64+
`packageManager` in the root `package.json`; `corepack enable` will pick it up
65+
automatically). Clone the repo, install once, and build all packages:
66+
67+
```sh
68+
git clone https://github.com/agentruntimecontrolprotocol/typescript-sdk.git
69+
cd typescript-sdk
70+
corepack enable
71+
pnpm install
72+
pnpm build
73+
```
74+
75+
A `simple-git-hooks` pre-commit hook runs Biome lint, `tsc`, and the test suite;
76+
it is installed automatically on `pnpm install`.
77+
78+
## Tests and conformance
79+
80+
Two layers must pass before a PR merges:
81+
82+
- **Unit tests** — this SDK's own suite:
83+
84+
```sh
85+
pnpm test
86+
```
87+
88+
- **Conformance** — the SDK's behavior against the reference runtime. New
89+
protocol-facing code (session negotiation, event sequencing, lease handling,
90+
error mapping) needs a test that exercises the real exchange, not a mock that
91+
assumes the answer. Because this SDK ships both `@agentruntimecontrolprotocol/client`
92+
and `@agentruntimecontrolprotocol/runtime` (it *is* the reference
93+
implementation), conformance tests run in-process by wiring the client to the
94+
runtime over the bundled `MemoryTransport`; the per-section spec mapping lives
95+
in [`CONFORMANCE.md`](CONFORMANCE.md), and the runnable end-to-end exchanges
96+
live under [`examples/`](examples/) and can be pointed at any conformant
97+
runtime via the `ARCP_DEMO_URL` / `ARCP_DEMO_TOKEN` environment variables.
98+
99+
CI runs both on every PR. A PR that changes which feature flags the SDK
100+
negotiates must also update the README feature matrix in the same change.
101+
102+
## Coding standards
103+
104+
This repo uses Biome (lint + format on source), ESLint (import / TSDoc /
105+
unicorn / n rules), Prettier (Markdown, JSON, YAML), and `tsc` for type
106+
checking. Run them via the workspace scripts:
107+
108+
```sh
109+
pnpm lint # biome lint . && eslint .
110+
pnpm lint:fix # auto-fix biome + eslint findings
111+
pnpm format # prettier --write .
112+
pnpm format:check # prettier --check . (CI)
113+
pnpm typecheck # tsc --noEmit across every workspace package
114+
pnpm check:all # lint + typecheck + test + cycle / attw / publint checks
115+
```
116+
117+
Match the surrounding code. Public API changes need doc comments and an entry in
118+
the changelog. Prefer clarity over cleverness in a library others build on.
119+
120+
## Commit and pull-request conventions
121+
122+
- Write focused commits with present-tense, imperative subjects
123+
(`add result_chunk reassembly`, not `added` / `adds`).
124+
- Reference the issue a PR closes (`Closes #123`).
125+
- Keep the PR description honest about scope and any spec sections touched.
126+
- Rebase on the default branch and ensure CI is green before requesting review.
127+
- Sign off your commits to certify the [Developer Certificate of Origin](https://developercertificate.org/):
128+
129+
```sh
130+
git commit -s -m "your message"
131+
```
132+
133+
- User-visible changes need a changeset. Run `pnpm changeset`, pick the affected
134+
packages and bump level, and commit the generated `.changeset/*.md` with your
135+
PR — the release workflow uses it to compute version bumps and changelogs.
136+
137+
## Releases
138+
139+
Releases are cut by maintainers. The workspace is managed with
140+
[Changesets](https://github.com/changesets/changesets): merging changeset files
141+
to `main` opens a "Version Packages" PR that bumps versions and writes
142+
per-package `CHANGELOG.md` files, and merging that PR triggers the `publish`
143+
workflow which publishes every changed `@agentruntimecontrolprotocol/*` package
144+
to npm with provenance. The SDK is versioned with semantic versioning
145+
independently of the protocol version it speaks; a protocol version bump is
146+
noted in the changelog when the negotiated ARCP version changes.
147+
148+
## License
149+
150+
By contributing, you agree that your contributions are licensed under the
151+
project's [Apache-2.0](LICENSE) license.

0 commit comments

Comments
 (0)