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

Commit Messages

• Commit messages must explain why the change is needed
• Keep messages clear and informative even if details are in the PR description

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. Title is clear and understandable for changelog