Skip to content

AGENTS.md

Latest commit

 

History

History
257 lines (191 loc) · 9.63 KB

AGENTS.md

File metadata and controls

257 lines (191 loc) · 9.63 KB

Agent Instructions for Gorums

Gorums is a framework for building fault-tolerant distributed systems using quorum-based abstractions. This document provides context and rules for AI coding assistants.

Project Overview

Gorums provides:

  • Flexible quorum call abstractions for distributed systems
  • Code generation via protoc-gen-gorums compiler plugin
  • gRPC-based RPC communication
  • Supported communication styles: unicast, multicast, quorumcall, async and correctable quorum calls

Key Technologies:

  • Language: Go 1.25+
  • Build: Make
  • Protocol: Protocol Buffers (protobuf)
  • Testing: Go testing framework
  • Code Generation: Custom protoc plugin

Repository Structure

gorums/
├── cmd/protoc-gen-gorums/     # Compiler plugin for code generation
│   ├── dev/                   # Static code + generated code examples
│   └── gengorums/             # Compiler logic + templates
├── benchmark/                 # Benchmarking code
├── examples/                  # Example implementations
├── internal/                  # Internal packages
├── doc/                       # Documentation
└── *.go                       # Core library files

Development Rules

General Guidelines

  • For larger features and refactors, prepare a plan before coding
  • STOP and ASK if unsure about design decisions
  • ALWAYS write tests for new features and bug fixes
  • Large changes must be broken into small, manageable units to be committed separately
  • NEVER make unrelated changes in the same commit (e.g., code + documentation + formatting)
  • Instead, if you discover a bug or issue while working, document the issue in a separate file doc/issue-*.md
  • COMMIT messages must follow conventional commit style (at most 75 characters wide), must be human readable plain text and easily copyable, and must not contain any markdown links or formatting.

Code Generation Workflow

NEVER directly edit files prefixed with zorums_*_gorums.pb.go in cmd/protoc-gen-gorums/dev/

These files are generated from templates. Instead:

  1. For Template Changes:

    • Edit template in cmd/protoc-gen-gorums/gengorums/template_*.go
    • Run make dev to regenerate zorums_*_gorums.pb.go files

  2. For Static Code Changes:

    • Edit files in cmd/protoc-gen-gorums/dev/ that are NOT prefixed with zorums_*
    • Run make dev to bundle changes into template_static.go

  3. After Any Template or Static Code Changes:

    • Run make dev to regenerate zorums_*_gorums.pb.go files
    • Or run make genproto to regenerate all _gorums.pb.go files

Testing Requirements

  • Use testing utilities in testing_shared.go for common test setup
  • If the provided testing utilities are insufficient, create new ones in testing_shared.go and document their usage
  • Always write table-driven tests when same logic needs to be tested with multiple inputs
  • Organize related tests using subtests
  • Test names should be capitalized, like TestFileNameFeatureName, e.g., TestQuorumCallFeatureName, for some feature in quorumcall_test.go
  • Run relevant tests after each change
  • NEVER delete failing tests - fix the underlying issue - unless the test is no longer relevant
  • NEVER skip tests or ignore failures
  • NEVER use another testing framework than Go's testing package
  • If addressing a test failure requires significant changes, stop and ask for guidance
  • Test coverage should be comprehensive
  • ALL tests must pass before considering work complete

Testing Strategy

  • Follow Test Driven Development (TDD) when adding features or fixing bugs:
    1. Write failing test
    2. Confirm test fails
    3. Write minimal code to pass test
    4. Confirm test passes
    5. Refactor if needed

Code Style and Conventions

  • Match existing code style - consistency within files is paramount

  • Follow Go conventions - use gofmt, follow effective Go practices

  • Use Go's standard library

    • use up-to-date standard library features when relevant
    • use recent versions of packages: slices, maps, sync, rand/v2
    • use for-range iterators with yield when applicable
    • use generics when appropriate

  • Use meaningful names - reflect domain concepts, not implementation details

  • Preserve comments unless they are demonstrably incorrect

  • Add documentation

    • Each exported function, type, and method must have a clear comment explaining its purpose and usage following Go doc conventions
    • Non-exported functions, types, and methods should have comments if their purpose is not immediately clear
    • Each Go package (typically in doc.go) should have a comment block describing its purpose:
    // Package gorums provides quorum call abstractions for distributed systems.
package gorums

  • Update user/developer documentation - whenever public APIs or behaviors change, update relevant documentation in doc/

Git Workflow

  • Main branch: master
  • Work on feature branches
  • Create new branches for significant changes, unless already working on a feature branch
  • Feature branches should be named: feature/short-description or fix/short-description
  • If there is an associated GitHub issue, include its ID in the branch name: feature/123/short-description
  • Commit individual units of work with clear, descriptive messages
  • Never use git add -A without first checking git status
  • Run tests before committing
  • DO NOT commit anything ever again unless explicitly asked to.
  • DEFINITELY DO NOT push ever, even if asked.

Building and Testing

Build Commands

# Generate `zorums_*_gorums.pb.go` files in `cmd/protoc-gen-gorums/dev/`
make dev

# Generate _gorums.pb.go files across the project
make genproto

# Build everything
make

# Force rebuild
make -B

# Install protoc-gen-gorums plugin
make installgorums

# Build benchmark tool
make benchmark

# Install required tools
make tools

Testing Commands

# Run all tests with verbose output and a timeout (use to avoid hanging tests)
go test -v -timeout=15s ./...

# Ensure tests are actually run (not skipped by cache)
go test ./... -count=1

# Run integration tests directly
go test -tags=integration ./...

Testing Modes

Gorums has two testing modes:

  • Default (bufconn): Uses in-memory connections for faster tests during development.
  • Integration: Uses real TCP connections with -tags=integration, for end-to-end validation.

For most development work, use the default bufconn mode. Use integration mode for performance benchmarking and network-specific validation.

Working with Protocol Buffers

  • Service definitions use .proto files
  • The protoc-gen-gorums plugin extends standard protobuf/gRPC generation
  • Generated files combine:
    • Standard protobuf Go code (.pb.go)
    • Standard gRPC Go code (_grpc.pb.go)
    • Gorums-specific code (_gorums.pb.go)

Custom Protobuf Options

Gorums provides custom protobuf options defined in gorums.proto:

  • Method-level options for quorum call types
  • Configuration options for RPC behavior
  • See doc/user-guide.md for details

Documentation

Before making significant changes, consult:

  • doc/user-guide.md - Understanding the API and usage patterns

  • doc/dev-guide.md - Development workflow and architecture

  • README.md - Project overview and getting started

  • When editing markdown files, use one sentences per line, so that diffs are easier to read.

Common Pitfalls to Avoid

  1. Editing Generated Files Directly - Always edit templates instead
  2. Skipping make After Changes - Templates must be regenerated
  3. Breaking Backward Compatibility - Require explicit approval from project maintainer
  4. Adding Unnecessary Features - Follow YAGNI (You Aren't Gonna Need It)
  5. Ignoring Test Failures - All tests must pass
  6. Inconsistent Code Style - Match surrounding code style
  7. Poor Commit Hygiene - Commit frequently with clear messages
  8. Committing Generated Files Together with Template Changes - Always commit templates and static code separately. Only commit generated files as the last step.

Performance Considerations

  • Gorums is used in performance-critical distributed systems
  • Benchmarking tools are available in benchmark/ and cmd/benchmark/
  • See doc/benchmarking.md for benchmarking procedures
  • Profile before optimizing - use Go's pprof tools

Communication with Project Maintainer

When uncertain:

  • STOP and ask rather than making assumptions
  • Clearly explain technical reasoning for design choices
  • Be honest about limitations or lack of understanding
  • Push back on bad ideas with technical justification
  • Discuss architectural changes before implementing them

Module and Dependency Management

  • Uses Go modules (go.mod, go.work)
  • Dependencies managed via go mod tidy
  • Tool dependencies declared in go.mod tool section
  • Examples have separate go.mod file

Quality Standards

  • Correctness over speed - take time to do it right
  • Simplicity over cleverness - prefer maintainable solutions
  • Consistency - match existing patterns and style in the codebase, call out deviations explicitly
  • Testing - comprehensive test coverage required
  • Documentation - keep docs in sync with code changes

Additional Resources