go-toml/AGENTS.md

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.

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:

  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

Documentation

• New features or feature extensions must include documentation
• Documentation lives in 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):

  # 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. 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