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