Skip to content

Commit 2139230

Browse files
JmPotatoJmPotato
authored
docs: add CLAUDE.md (#10207)
ref #10206 Introduce a new developer guide (CLAUDE.md) tailored for Claude Code and human contributors. Signed-off-by: JmPotato <github@ipotato.me>
1 parent 92e0ed9 commit 2139230

File tree

1 file changed

+176
-0
lines changed

1 file changed

+176
-0
lines changed

‎CLAUDE.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
PD (Placement Driver) is the cluster manager for TiKV. It handles metadata storage, timestamp allocation (TSO), and scheduling decisions for TiKV clusters. PD embeds etcd for fault-tolerance and leader election.
8+
9+
## Build Commands
10+
11+
```bash
12+
make # Build pd-server, pd-ctl, pd-recover
13+
make pd-server # Build only pd-server
14+
make pd-server-basic # Build without dashboard (SWAGGER=0 DASHBOARD=0, faster)
15+
make tools # Build benchmark and utility tools
16+
make install-tools # Install dev tools to .tools/bin (golangci-lint v2.6.0, etc.)
17+
18+
# Build variants
19+
WITH_RACE=1 make build # Enable race detector (CGO on)
20+
SWAGGER=1 make build # Generate swagger spec
21+
ENABLE_FIPS=1 make build # FIPS/boringcrypto build
22+
NEXT_GEN=1 make build # NextGen mode (disables dashboard)
23+
make simulator # Build pd-simulator
24+
make docker-image # Build Docker image
25+
```
26+
27+
**Go version requirement: >=1.25**
28+
29+
## Testing
30+
31+
```bash
32+
make test # Full suite with race detection, deadlock tag, failpoints
33+
make basic-test # Fast tests without race (excludes tests/ packages)
34+
make ut # Unit tests only via pd-ut binary (excludes tests/ directory)
35+
make test-tso-function # TSO-specific tests
36+
37+
# Run a single test (uses gocheck)
38+
go test github.com/tikv/pd/server/api -check.f TestJsonRespondError
39+
go test ./pkg/schedule/... -run TestSpecificTest
40+
41+
# Integration tests (in tests/integrations/)
42+
cd tests/integrations && make test test_name=client
43+
cd tests/integrations && make test test_name=mcs
44+
45+
# Real cluster tests
46+
make test-real-cluster # Uses tiup, wipes ~/.tiup/data/pd_real_cluster_test
47+
48+
# Cleanup
49+
make clean-test # Remove /tmp/pd_tests*, test cache, UT binaries
50+
```
51+
52+
### Failpoints
53+
54+
Tests use failpoints which must be enabled/disabled properly:
55+
- `make failpoint-enable` / `make failpoint-disable`
56+
- Make targets auto-enable/disable; if running `go test` manually, bracket with enable/disable
57+
- Never commit with failpoints enabled; verify `git status` is clean before pushing
58+
59+
## Linting
60+
61+
```bash
62+
make check # Full check: tidy + static + generate-errdoc
63+
make static # gofmt -s + golangci-lint + leakcheck
64+
make tidy # go mod tidy (CI enforces clean diff)
65+
make fmt # gofmt with interface{} -> any rewrite
66+
make generate-errdoc # Regenerate errors.toml
67+
make generate-easyjson # Update pkg/response/region.go
68+
```
69+
70+
## Architecture
71+
72+
### Multi-module Structure
73+
74+
The project has multiple Go modules with separate go.mod files:
75+
- Root module (`github.com/tikv/pd`)
76+
- `client/` - PD client library (run `make` from client/ for its pipeline)
77+
- `tools/` - CLI tools and utilities
78+
- `tests/integrations/` - Integration tests
79+
80+
### Core Components
81+
82+
**Server (`server/`):**
83+
- `api/` - REST API v1 endpoints
84+
- `apiv2/` - REST API v2 with modern handlers
85+
- `cluster/` - Cluster state and region management
86+
- `grpc_service.go` - gRPC service implementation
87+
88+
**Scheduling (`pkg/schedule/`):**
89+
- `coordinator.go` - Main scheduling loop
90+
- `schedulers/` - 20+ scheduler implementations (balance-leader, balance-region, etc.)
91+
- `checker/` - Data integrity checkers (replica, merge, rule)
92+
- `operator/` - Scheduling operations execution
93+
- `placement/` - Placement rules engine
94+
95+
**TSO (`pkg/tso/`):**
96+
- Timestamp Oracle for distributed transaction ordering
97+
- Keyspace group management for multi-tenancy
98+
99+
**Core Data Structures (`pkg/core/`):**
100+
- `BasicCluster` - Cluster metadata container
101+
- `RegionsInfo` - Region tree and index management
102+
- `StoresInfo` - Store (TiKV node) information
103+
104+
**Storage (`pkg/storage/`):**
105+
- Backend abstraction (etcd, LevelDB, memory)
106+
- Endpoint interfaces for different data types
107+
108+
### Microservices Mode (`pkg/mcs/`)
109+
110+
PD supports running services as separate microservices:
111+
- `tso/` - Distributed TSO service
112+
- `scheduling/` - Scheduling service
113+
- `resourcemanager/` - Resource group management
114+
115+
Start microservices: `pd-server services <api|tso|scheduling|resource-manager>`
116+
117+
### Client Library (`client/`)
118+
119+
- `client.go` - Main PD client for TiKV communication
120+
- `clients/tso/` - TSO client
121+
- `servicediscovery/` - Service discovery
122+
- `resource_group/` - Resource management client
123+
124+
## Code Conventions
125+
126+
### Imports and Formatting
127+
- Import order (gci enforced): standard | third-party | `github.com/pingcap` | `github.com/tikv/pd` | blank
128+
- Run `make fmt` for gofmt with `interface{}` -> `any` rewrite
129+
- Avoid dot-imports (revive warns)
130+
131+
### Banned Packages (depguard enforced)
132+
- Use `github.com/pingcap/errors` (not `github.com/pkg/errors`)
133+
- Use `sync/atomic` (not `go.uber.org/atomic`)
134+
- Use `math/rand/v2` (not `math/rand`)
135+
136+
### Error Handling
137+
- Wrap errors with `errors.Wrap`/`errors.Annotate` or `fmt.Errorf("...: %w", err)`
138+
- Error strings: lowercase, no trailing punctuation
139+
- HTTP handlers: use errcode + `errorResp` (avoid `http.Error`)
140+
- Check errors with `errors.Is`/`errors.As` for sentinel errors
141+
142+
### Style
143+
- First parameter `context.Context` for functions with external effects; never store in structs
144+
- Acronyms uppercase: TSO, API, HTTP
145+
- `sync.WaitGroup` must be passed as pointer (revive rule)
146+
- Pointers for large structs; avoid pointer-to-interface
147+
- All files require Apache 2.0 license header (goheader enforced)
148+
149+
### Concurrency
150+
- Cancel timers/tickers; close resources with defer
151+
- Guard shared state with mutex; keep lock ordering consistent
152+
- Prevent goroutine leaks: pair with cancellation; consider errgroup
153+
154+
## API and Swagger
155+
156+
```bash
157+
SWAGGER=1 make build # Regenerate swagger spec
158+
make swagger-spec # Generate docs/swagger/ from annotations
159+
make generate-easyjson # Update easyjson for pkg/response/region.go
160+
```
161+
162+
Update Go annotations when changing APIs. Format reference: [swaggo/swag](https://github.com/swaggo/swag#declarative-comments-format)
163+
164+
## Commit Requirements
165+
166+
- Sign off commits: `git commit -s -m "message"`
167+
- PR title format: `pkg: description` (under 70 chars); multi-area use commas or `*:`
168+
- PRs must include: `Issue Number: close #123` or `Issue Number: ref #456`
169+
- Body wrapped at 80 chars
170+
171+
## Pre-PR Checklist
172+
173+
1. Run `make check` (or at minimum `make basic-test` for touched packages)
174+
2. Ensure imports ordered, gofmt clean, modules tidy
175+
3. Verify `git status` clean (no failpoint artifacts, generated files)
176+
4. Fix all depguard, revive, testifylint findings before submission

0 commit comments

Comments
 (0)