golang/AGENTS.md

Development Guidelines

This document outlines the best practices for Go development and Git workflow to be followed by the Gemini agent for this project.

Go Development Guidelines

Code Quality and Style

• Formatting: All Go code MUST be formatted with gofmt before committing.
• Linting: Use golangci-lint to enforce code quality and style.
• Simplicity: Write simple, clear, and concise code. Avoid unnecessary complexity.
• Error Handling: Handle all errors explicitly. Never ignore an error. Check for errors and return them from functions.
• Naming: Use meaningful and descriptive names for variables, functions, and packages. Follow Go's naming conventions (e.g., camelCase for private, PascalCase for public).
• Comments: Write comments to explain the why behind complex or non-obvious code, not the what. Document all public functions and packages.
• Testing:
  • Write unit tests for all new code. Aim for high test coverage.
  • Use table-driven tests for testing multiple scenarios.
  • Mocks and interfaces should be used to isolate dependencies for testing.
• Dependencies: Use Go modules (go mod) to manage project dependencies. Keep the go.mod and go.sum files up-to-date.

Best Practices

• Concurrency: When using goroutines, ensure proper synchronization to avoid race conditions. Use channels for communication between goroutines.
• Interfaces: Use interfaces to define behavior and decouple components.
• Packages: Structure your code into logical packages. Avoid circular dependencies.
• Security: Be mindful of security best practices. Sanitize inputs, avoid SQL injection, and handle credentials securely.

Git Workflow Best Practices

Branching

• Main Branch: The main branch is for production-ready code only. Direct commits to main are NOT allowed.
• Feature Branches: Create a new branch for every new feature or bug fix.
  • Branch names should be descriptive and follow the pattern feature/<short-description> or fix/<short-description> (e.g., feature/user-auth, fix/login-bug).
• Pull Requests (PRs): All changes must be submitted through a Pull Request to the main branch.

Committing

• Atomic Commits: Each commit should represent a single, logical change. Do not bundle unrelated changes into one commit.
• Commit Messages: Follow the Conventional Commits specification. This helps in automating changelogs and versioning.
  • Format: <type>[optional scope]: <description>
  • Example: feat: add user login endpoint
  • Common types: feat, fix, docs, style, refactor, test, chore.

Pull Request (PR) Process

1. Create a PR: When your feature or fix is complete, create a PR against the main branch.
2. CI Checks: Ensure all automated checks (build, tests, linting) pass.
3. Code Review: The PR will be reviewed. Address any feedback by pushing new commits to your branch.
4. Merge: Once the PR is approved and all checks pass, it will be merged into main.