ezcache/AGENTS.md

Agent Guidelines for ezcache

This document outlines the conventions and commands for agents operating within the ezcache Go project.

Build/Lint/Test Commands

• Build: go build ./...
• Lint: task lint
• Test All: task test
• Test Single File: go test -run <TestName> <path/to/file_test.go> (e.g., go test -run TestNewHappy ./ezcache_test.go)
• Format: task fmt

Code Style Guidelines

• Module: codeberg.org/danjones000/ezcache
• Go version: 1.23.7
• Imports: Group standard library imports separately from third-party imports.
• Formatting: Adhere to go fmt standards.
• Naming Conventions:
  • Variables: camelCase
  • Functions/Methods: CamelCase (exported), camelCase (unexported)
  • Packages: lowercase
• Error Handling: Return errors explicitly. Check errors immediately after a function call that returns an error.
• Types: Use generics where appropriate, as seen in ezcache.go.
• Concurrency: Use sync.RWMutex for concurrent map access, as demonstrated in ezcache.go.
• Linter Rules: Refer to .golangci.yaml for detailed linting rules.
• Testing: Use github.com/nalgeon/be

Git Commit Guidelines

• Format: Prepend commit messages with a gitmoji emoji (see https://gitmoji.dev)
• Style: Write detailed commit messages that explain what changed and why
• Examples: ✨ Add JSON export functionality for log entries, 🐛 Fix date parsing for RFC3339 timestamps, 📝 Update README with configuration examples

Git Flow Workflow

• Main branches: stable (production-ready), develop (integration branch)
• Development: Always commit new features/fixes to develop branch or appropriate feature branches
• Branch prefixes:
  • feat/feature-name - New features, merge to develop when complete
  • bug/bug-name - Bug fixes (non-urgent), merge to develop when complete
  • rel/version - Release preparation branches, merge to stable and then also merge stable back to develop
  • hot/version - Hotfixes for production issues follow same merge rules as releases
• Version tags: Prefix all version tags with v (e.g., v1.0.2, v0.0.6)
• Releases: Update CHANGELOG.md with a summary of changes for each new version
• Never commit directly to stable branch (only merge from rel/ or hot/ branches)
• After merging to stable, always merge it back to develop
• Before starting work: Ensure you're on develop branch or create an appropriate feature branch from it