Claude
20a7856820
Replace the full JSON baseline with a simple text file listing capability names per package. Add caps.sh script to generate and check the baseline. Document in CONTRIBUTING.md and AGENTS.md that PRs increasing capabilities are unlikely to be accepted. https://claude.ai/code/session_01HwDXpKevFLhE5EfrR6JrBn
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
# Agent Guidelines for go-toml
|
|
|
|
This file provides guidelines for AI agents contributing to go-toml. All agents must follow these rules derived from [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
|
|
## Project Overview
|
|
|
|
go-toml is a TOML library for Go. The goal is to provide an easy-to-use and efficient TOML implementation that gets the job done without getting in the way.
|
|
|
|
## Code Change Rules
|
|
|
|
### Backward Compatibility
|
|
|
|
- **No backward-incompatible changes** unless explicitly discussed and approved
|
|
- Avoid breaking people's programs unless absolutely necessary
|
|
|
|
### Testing Requirements
|
|
|
|
- **All bug fixes must include regression tests**
|
|
- **All new code must be tested**
|
|
- Run tests before submitting: `go test -race ./...`
|
|
- Test coverage must not decrease. Check with:
|
|
```bash
|
|
go test -covermode=atomic -coverprofile=coverage.out
|
|
go tool cover -func=coverage.out
|
|
```
|
|
- All lines of code touched by changes should be covered by tests
|
|
|
|
### Performance Requirements
|
|
|
|
- go-toml aims to stay efficient; avoid performance regressions
|
|
- Run benchmarks to verify: `go test ./... -bench=. -count=10`
|
|
- Compare results using [benchstat](https://pkg.go.dev/golang.org/x/perf/cmd/benchstat)
|
|
|
|
### Documentation
|
|
|
|
- New features or feature extensions must include documentation
|
|
- Documentation lives in [README.md](./README.md) and throughout source code
|
|
|
|
### Code Style
|
|
|
|
- Follow existing code format and structure
|
|
- Code must pass `go fmt`
|
|
- Code must pass linting with the same golangci-lint version as CI (see version in `.github/workflows/lint.yml`):
|
|
```bash
|
|
# Install specific version (check lint.yml for current version)
|
|
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin <version>
|
|
# Run linter
|
|
golangci-lint run ./...
|
|
```
|
|
|
|
### Commit Messages
|
|
|
|
- Commit messages must explain **why** the change is needed
|
|
- Keep messages clear and informative even if details are in the PR description
|
|
|
|
### Capabilities
|
|
|
|
go-toml tracks system-level capabilities using [capslock](https://github.com/google/capslock). The baseline is in `capability_baseline.txt` and CI enforces that it does not grow.
|
|
|
|
- **Do not introduce new capabilities.** PRs that increase the capability set (e.g., adding network access, subprocess execution, syscalls) are unlikely to be accepted.
|
|
- If a change causes the capabilities check to fail, do not update the baseline to make it pass. Instead, rethink the approach to avoid requiring new capabilities.
|
|
- To check locally: `./caps.sh check` (requires `capslock` installed via `go install github.com/google/capslock/cmd/capslock@latest`)
|
|
|
|
## Pull Request Checklist
|
|
|
|
Before submitting:
|
|
|
|
1. Tests pass (`go test -race ./...`)
|
|
2. No backward-incompatible changes (unless discussed)
|
|
3. Relevant documentation added/updated
|
|
4. No performance regression (verify with benchmarks)
|
|
5. Capabilities are not increasing (`./caps.sh check`)
|
|
6. Title is clear and understandable for changelog
|