Skip to content

Commit de12fa1

Browse files
kochj23Jordan Kochclaude
authored
docs: add CONTRIBUTING guide (#67)
Adds a concise CONTRIBUTING.md pointing at the existing developer docs (docs/development.md), the taskfile targets, the conventional-commit / semantic-release convention, and PR expectations. No existing CONTRIBUTING file was present. Co-authored-by: Jordan Koch <kochj23@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 6232629 commit de12fa1

1 file changed

Lines changed: 40 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Contributing
2+
3+
Thanks for your interest in improving critical-thinking! This is a short pointer to the conventions already documented in the repo.
4+
5+
## Getting started
6+
7+
The full developer guide lives in **[docs/development.md](docs/development.md)** — toolchain (Go 1.26+), build, test, project layout, and how to exercise the tool with the MCP Inspector. Start there.
8+
9+
Common tasks are wired into [`taskfile.yml`](taskfile.yml) (install [Task](https://taskfile.dev), then run `task --list`):
10+
11+
```bash
12+
task build # build the binary into bin/
13+
task test # go test ./...
14+
task test-race # race detector + coverage (the standard mode for this project)
15+
task vet # go vet ./...
16+
task lint # golangci-lint run ./...
17+
```
18+
19+
`-race` is the expected test mode here — the HTTP path has non-trivial concurrency invariants that a plain `go test` will not catch. Run `task vet` and `gofmt -d .` clean before pushing; CI runs `vet`, `gofmt`, `go test -race`, and a Docker build on every push and PR.
20+
21+
## Commit messages
22+
23+
Releases are automated with [semantic-release](https://github.com/semantic-release/semantic-release), so commits must follow [Conventional Commits](https://www.conventionalcommits.org/):
24+
25+
| Type | Effect |
26+
|------|--------|
27+
| `fix: ...` | Patch release |
28+
| `feat: ...` | Minor release |
29+
| `feat!: ...` / `BREAKING CHANGE:` | Major release |
30+
| `chore:`, `docs:`, `test:`, `ci:` | No release |
31+
32+
## The tool description is a protocol
33+
34+
The string in [`internal/thinking/description.go`](internal/thinking/description.go) is the contract every client agent reads. Treat changes there like wire-format changes — bump the package version and add an entry to [docs/migration.md](docs/migration.md). See the "Treating the description as a protocol" section in [docs/development.md](docs/development.md) for details.
35+
36+
## Pull requests
37+
38+
- Open PRs against `main` from a topic branch.
39+
- Keep changes focused; include tests for behavior changes (`internal/thinking` is fully unit-testable by design).
40+
- Make sure `task test-race`, `task vet`, and `task lint` pass locally.

0 commit comments

Comments
 (0)