From 49e470b10dfdd486768d427d7826bc5c48e5e16a Mon Sep 17 00:00:00 2001 From: Dan Jones Date: Tue, 11 Nov 2025 12:01:26 -0600 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20agent=20guidelines=20and?= =?UTF-8?q?=20conventions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d40bae2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,45 @@ +# 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 ` (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 + - `hot/version` - Hotfixes for production issues, merge to **both** `stable` and `develop` + - `rel/version` - Release preparation branches +- **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) +- **Before starting work**: Ensure you're on `develop` branch or create an appropriate feature branch from it