Skip to content

Commit a642f8d

Browse files
mboss37claude
mboss37
and
claude
committed
docs: add TrustScript-specific CONTRIBUTING guide (E6.3 down-payment)
Seeds contributor culture now rather than at M6 — Non-Negotiable salesforce#5 (public-by-default development) doesn't wait until launch. docs/v2/CONTRIBUTING.md covers: - What we accept / won't accept without a prior ADR - Setup with the Node 22 pin callout (Node 24 breaks tree-sitter) - Change flow: issue first, small PRs, conventional commits, docs in the same PR - Code conventions inherited from .claude/rules plus TrustScript- specific copyright-header + SPDX rules - New-package checklist - ADR template + numbering rule Explicit scope limits: - TrustScript packages + docs/v2/ only; upstream AgentScript PRs still use repo-root CONTRIBUTING.md - Release process, security disclosure, conformance submission, and governance docs are called out as "not yet" so the omissions don't look like oversights Traces to ROADMAP E6.3 (Contributor onboarding docs). Long lead time, so shipping now beats shipping at M6 and hoping contributors already showed up. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent aba5009 commit a642f8d

1 file changed

Lines changed: 150 additions & 0 deletions

File tree

‎docs/v2/CONTRIBUTING.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Contributing to TrustScript
2+
3+
> This guide is for `@trustscript/*` packages and `docs/v2/`. For upstream AgentScript contributions, see the repo-root `CONTRIBUTING.md`.
4+
5+
## What we're building
6+
7+
TrustScript is an Apache-2.0 fork of AgentScript that adds compiler-enforced trust primitives. Read [VISION.md](./VISION.md) first — it takes 5 minutes and everything below presumes you've seen it.
8+
9+
## Before you open a PR
10+
11+
Read these, in order:
12+
1. [VISION.md](./VISION.md) — thesis and non-negotiables
13+
2. [ROADMAP.md](./ROADMAP.md) — current milestone and exit criteria
14+
3. [BACKLOG.md](../../BACKLOG.md) §Quick Guide — how epics flow into sprints
15+
4. Relevant ADR(s) for the area you're touching (`docs/v2/adr/`)
16+
17+
If your contribution conflicts with a non-negotiable, it doesn't merge. If it conflicts with an ADR, either (a) your ADR supersedes it — write one, or (b) open an issue before the PR so we can discuss.
18+
19+
## What we accept
20+
21+
- **Bug fixes** to `@trustscript/*` packages
22+
- **Test coverage** for existing code (Vitest)
23+
- **Documentation** improvements
24+
- **New runtime sink adapters** that pass the conformance suite (M3+)
25+
- **Tier-2 LLM adapters** that pass the LLM-adapter conformance suite (per [ADR-0002](./adr/0002-llm-abstraction-strategy.md))
26+
- **Conforming runtime implementations** from external teams (M3+ — this is how the portability thesis gets proven)
27+
28+
## What we won't accept without a prior ADR
29+
30+
- New primitives that change the language (`@foo` keywords)
31+
- IR schema changes beyond additive fields
32+
- Breaking changes to `@trustscript/ir`, `@trustscript/runtime`, or `@trustscript/llm` public APIs
33+
- Dependencies on proprietary services or closed-source SDKs
34+
- Features requiring a Salesforce account or Agentforce runtime
35+
- Anything that relies on runtime enforcement when compile-time is feasible (Non-Negotiable #4)
36+
37+
## Setting up
38+
39+
```bash
40+
# Node 22.x required (Volta pin in package.json); Node 24 breaks tree-sitter 0.25 native build
41+
volta install node@22 # or: fnm use 22
42+
git clone <your-fork>
43+
cd agentscript
44+
pnpm install
45+
pnpm build
46+
pnpm test
47+
```
48+
49+
Commands:
50+
- `pnpm dev` — Turbo watches all packages
51+
- `pnpm test` — Vitest across the monorepo
52+
- `pnpm typecheck` — strict TS across all packages
53+
- `pnpm lint` — ESLint flat config
54+
- `pnpm --filter @trustscript/runtime test` — scoped to one package
55+
56+
## How a change flows
57+
58+
1. **Pick work from BACKLOG.md** `[pending]` epics. If you want to work on something blocked, resolve the blocker first or pick a different epic.
59+
2. **Open an issue first** for any non-trivial change. Sketch the approach; get a review before coding.
60+
3. **Branch off main.** Feature branches stay short-lived (<1 week).
61+
4. **Write tests first** where practical. Vitest; one assertion per test when possible.
62+
5. **Keep PRs small.** <400 lines changed. Split if larger.
63+
6. **Conventional commits** — `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
64+
7. **Update docs in the same PR** as the code change. TrustScript docs in `docs/v2/`; ADRs in `docs/v2/adr/`.
65+
8. **Sign your commits** (DCO) if you're contributing on behalf of an organization.
66+
67+
## Code conventions
68+
69+
Inherited from `.claude/rules/conventions.md`:
70+
- Files under 400 lines, functions under 50 lines
71+
- Named exports, no default exports
72+
- Explicit error handling — no empty catch blocks
73+
- Validate input at system boundaries (parser, runtime entry, CLI argv)
74+
- **No `any` types.** Ever. If you need to escape the type system, use `unknown` and narrow.
75+
76+
TrustScript-specific:
77+
- **Copyright header** on every new file:
78+
```
79+
/*
80+
* Copyright (c) 2026 TrustScript contributors
81+
* SPDX-License-Identifier: Apache-2.0
82+
*/
83+
```
84+
- Files modified from upstream `@agentscript/*` carry an additional `/* modified by TrustScript contributors */` line. (Not required during M1 additive-in-place dev; enforced at M1 close per ADR-0014.)
85+
- Every runtime feature ships with a conformance test when the conformance suite exists (M3+).
86+
87+
## Review expectations
88+
89+
- Core team reviews within 3 business days for straightforward changes.
90+
- Architectural PRs (new packages, schema changes, ADRs) get a deeper review — budget a week.
91+
- Reviews focus on: correctness, type safety, conformance, non-negotiable alignment. Style is linter's job.
92+
- Reviews are public-by-default per Non-Negotiable #5. Don't expect private feedback channels.
93+
94+
## Adding a new package
95+
96+
If you're creating `@trustscript/foo`:
97+
1. `packages/trustscript-foo/` directory
98+
2. `package.json` with `@trustscript/foo` scope, Apache-2.0 license, `type: "module"`
99+
3. `tsconfig.json` extending the root config
100+
4. `src/index.ts` with copyright header
101+
5. README with at minimum: purpose, exports, milestone it targets
102+
6. Register in `pnpm-workspace.yaml` — it auto-picks up `packages/*`
103+
7. Add dependency line to any package consuming it: `"@trustscript/foo": "workspace:*"`
104+
105+
## Working with ADRs
106+
107+
Every architectural decision gets an ADR. Template:
108+
109+
```
110+
# ADR-NNNN: <one-line summary>
111+
**Status**: Proposed | Accepted | Superseded by ADR-NNNN
112+
**Date**: YYYY-MM-DD
113+
**Deciders**: <names or "core team">
114+
115+
## Context
116+
What's the forcing question? What's the constraint?
117+
118+
## Options considered
119+
1. ...
120+
2. ...
121+
3. ...
122+
123+
## Decision
124+
We chose X because Y.
125+
126+
## Consequences
127+
- Good: ...
128+
- Bad: ...
129+
- Reversibility: yes / no / expensive
130+
131+
## Follow-ups
132+
- Any downstream ADRs or open questions.
133+
```
134+
135+
Number sequentially from the highest existing ADR. Don't skip or renumber.
136+
137+
## Reporting security issues
138+
139+
Do not open a public issue for security vulnerabilities. Email the maintainers (contact TBD before M2) or use GitHub's private vulnerability reporting.
140+
141+
## Licensing
142+
143+
All contributions are Apache-2.0. By submitting a PR, you affirm your contribution complies with Apache-2.0 §5 (contribution licensing) and is yours to contribute.
144+
145+
## What this doc does NOT cover yet
146+
147+
- Release process (changesets workflow) — docs land at M2 with the first non-foundational release
148+
- Security disclosure process — formalized at M3 alongside signed tool catalog
149+
- Conformance test submission process — defined at M3 when `@trustscript/conformance` ships
150+
- Maintainer succession / governance — formalized only if the project grows to warrant it

0 commit comments

Comments
 (0)