CONTRIBUTING.md

Contributing to Goroutine Lab

Thanks for your interest — contributions are very welcome, and adding a new concurrency pattern is a great first PR.

Questions & discussion

Open a GitHub issue for questions, bugs, or ideas. There's no separate forum or chat.

Pull requests

PRs are accepted and appreciated. There are no CLA or commit sign-off requirements — just:

1. Fork and branch off master.
2. Keep the change focused and match the surrounding style (the code leans on the Go standard library only; the frontend is dependency-free React + Vite).
3. Make sure it builds and the checks pass (see below).
4. Open the PR with a short description of what and why.

Local checks

# backend
cd backend
go build ./...
go vet ./...
go test ./...          # includes the source-mapping coherence test

# frontend
cd frontend
npm install
npx tsc --noEmit       # type-check
npm run build

Adding a new pattern

Each demo is one self-contained, real piece of concurrent Go that narrates itself through the tracer so the UI can animate it.

1. Create backend/internal/patterns/my_pattern.go.

2. In an init(), register it:

   func init() {
       register(&Pattern{
           ID:       "my-pattern",
           Name:     "My Pattern",
           Category: "Core Patterns",
           Order:    99,
           File:     "my_pattern.go",
           Summary:  "One-line description.",
           Docs:     "Markdown: how it works.",
           Interview: "Markdown: what an interviewer probes.",
           run:      runMyPattern,
       })
   }

3. Write func runMyPattern(ctx context.Context, t *trace.Tracer) error using the tracer helpers (t.Spawn, t.NewChan, t.Send, t.Recv, t.Lock, t.Pace, t.Exit, …). Use t.Pace(ctx, d) for the watchable delays — it's the one call that also honours cancellation.

4. Restart the backend; the pattern appears in the sidebar automatically, with the trace hooks stripped from the "Go source" tab so learners read only the concept.

The tracer API is small — read internal/trace/trace.go and copy any existing pattern (goroutines.go is a good template).

Please keep demos correct, idiomatic, and interview-defensible: this is a learning tool first.