dance-lessons-coach/CONTRIBUTING.md

# Contributing to dance-lessons-coach

Thank you for your interest in contributing to dance-lessons-coach! This guide will help you set up your development environment and understand our contribution process.

## 📋 Table of Contents

1. [Development Setup](#development-setup)
2. [Code Style](#code-style)
3. [Commit Process](#commit-process)
4. [Testing](#testing)
5. [Documentation](#documentation)
6. [Pull Request Process](#pull-request-process)

## 🔧 Development Setup

### Prerequisites

- Go 1.26.1+
- Docker (for local testing)
- Git
- Make (optional, for convenience scripts)

### Installation

```bash
# Clone the repository
git clone https://gitea.arcodange.lab/arcodange/dance-lessons-coach.git
cd dance-lessons-coach

# Install dependencies
go mod tidy

# Install development tools
go install github.com/swaggo/swag/cmd/swag@latest

# Set up git hooks
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

### Git Hooks

We use git hooks to enforce code quality:

- **pre-commit**: Runs `go fmt` and `swag fmt` automatically
- **Commit message validation**: Enforces conventional commits

To enable hooks:
```bash
chmod +x .git/hooks/pre-commit
```

## 🎨 Code Style

### Go Formatting

We use `go fmt` for Go code formatting:
```bash
go fmt ./...
```

### Swagger Formatting

We use `swag fmt` to format swagger comments:
```bash
swag fmt
```

This is automatically run in:
- Pre-commit hook
- CI/CD lint-format job

### Commit Messages

We follow [Conventional Commits](https://www.conventionalcommits.org/):

```bash
# Good examples
git commit -m "feat: add new API endpoint"
git commit -m "fix: resolve race condition"
git commit -m "docs: update README"
git commit -m "chore: update dependencies"

# Types:
# - feat: New feature
# - fix: Bug fix
# - docs: Documentation changes
# - style: Formatting, missing semicolons, etc.
# - refactor: Code refactoring
# - perf: Performance improvements
# - test: Adding missing tests
# - chore: Maintenance tasks
```

## 🔄 Commit Process

### Before Committing

1. **Run tests**: Ensure all tests pass
   ```bash
   go test ./...
   ```

2. **Format code**: Run formatting tools
   ```bash
   go fmt ./...
   swag fmt
   ```

3. **Build project**: Ensure it compiles
   ```bash
   go build ./...
   ```

4. **Generate docs**: Update swagger documentation
   ```bash
   cd pkg/server && go generate
   ```

### Making Changes

1. **Create a branch**: Use a descriptive name
   ```bash
   git checkout -b feat/add-new-feature
   git checkout -b fix/resolve-issue
   ```

2. **Make your changes**: Follow code style guidelines

3. **Commit**: Use conventional commit messages
   ```bash
   git add .
   git commit -m "feat: add new feature"
   ```

4. **Push**: Push to your fork or branch
   ```bash
   git push origin feat/add-new-feature
   ```

## 🧪 Testing

### Unit Tests

```bash
# Run all tests
go test ./...

# Run with coverage
go test ./... -cover

# Run specific package
go test ./pkg/greet/ -v
```

### Integration Tests

```bash
# Run local CI/CD test
./scripts/test-local-ci-cd.sh

# Test Docker build
./scripts/test-local-ci-cd.sh  # Follow prompts to build Docker image
```

### BDD Tests

```bash
# Run BDD tests
./scripts/run-bdd-tests.sh
```

## 📚 Documentation

### Swagger Documentation

We use swaggo for API documentation:

```bash
# Generate swagger docs
cd pkg/server && go generate

# Access Swagger UI (after starting server)
open http://localhost:8080/swagger/
```

### Adding Swagger Comments

```go
// @Summary Get user by ID
// @Description Returns user information
// @Tags API/v1/Users
// @Accept json
// @Produce json
// @Param id path int true "User ID"
// @Success 200 {object} UserResponse
// @Failure 404 {object} ErrorResponse
// @Router /v1/users/{id} [get]
func (h *UserHandler) GetUser(w http.ResponseWriter, r *http.Request) {
    // ...
}
```

## 🔀 Pull Request Process

1. **Open a Pull Request**: Target the `main` branch
2. **Describe changes**: Explain what and why
3. **Link issues**: Reference related issues (e.g., "Fixes #123")
4. **Wait for review**: Address feedback from maintainers
5. **Merge**: Once approved, a maintainer will merge

### CI/CD Pipeline

All pull requests trigger our CI/CD pipeline:
- **Build & Test**: Runs tests and builds binaries
- **Lint & Format**: Checks formatting with `go fmt` and `swag fmt`
- **Version Check**: Analyzes commits for version bumps
- **Docker Build**: Builds Docker image (on main branch)

## 🎯 Best Practices

### Code Organization

- Keep handlers thin, move logic to services
- Use interfaces for dependencies
- Separate route registration from handlers
- Group related functionality

### Error Handling

- Return proper HTTP status codes
- Log errors with context
- Don't expose internal errors to clients
- Use structured error responses

### Performance

- Avoid allocations in hot paths
- Use context timeouts for external calls
- Batch database operations
- Use efficient data structures

### Testing

- Test interfaces, not implementations
- Use table-driven tests
- Test error cases
- Mock dependencies

## 📝 Architecture Decisions

Major architectural decisions are documented in the `adr/` directory. Please review relevant ADRs before making significant changes.

### Key ADRs

- [ADR-0001: Go 1.26.1 Standard](adr/0001-go-1.26.1-standard.md)
- [ADR-0002: Chi Router](adr/0002-chi-router.md)
- [ADR-0003: Zerolog Logging](adr/0003-zerolog-logging.md)
- [ADR-0013: OpenAPI/Swagger Toolchain](adr/0013-openapi-swagger-toolchain.md)

## 🤖 AI Agent Contributions

AI agents play a crucial role in maintaining and improving dance-lessons-coach. This section provides guidance for AI agents on how to effectively contribute.

### Key Files and Directories

**Core System:**
- `cmd/server/main.go` - Main server entry point with swagger metadata
- `pkg/server/server.go` - Server implementation with `go:generate` directive
- `pkg/greet/` - Greet service implementation
- `.gitea/workflows/` - CI/CD workflows

**Documentation:**
- `adr/` - Architecture Decision Records
- `CONTRIBUTING.md` - Contribution guidelines
- `README.md` - Project overview

**Scripts:**
- `scripts/` - Utility scripts for development
- `.git/hooks/` - Git hooks for automation

### Skills to Use/Improve

**Existing Skills:**
- `bdd-testing` - Behavior-Driven Development testing
- `skill-creator` - Skill creation and management
- `gitea-client` - Gitea API interactions

**Skills to Develop:**
- `ci-cd-optimization` - CI/CD pipeline improvements
- `version-management` - Automatic version bumping
- `artifact-management` - Build artifact optimization
- `documentation-generation` - Automatic doc updates

### Continuous Improvement Areas

**CI/CD Pipeline:**
- Optimize job dependencies and artifact passing
- Improve version bumping logic based on commit analysis
- Enhance Docker build caching and layer optimization
- Add more comprehensive test coverage

**Code Quality:**
- Expand swag fmt integration to other comment types
- Add additional linting checks
- Improve test automation
- Enhance error handling patterns

**Documentation:**
- Auto-generate ADR templates
- Improve API documentation completeness
- Add more examples and tutorials
- Keep documentation in sync with code

**Monitoring:**
- Add CI/CD performance metrics
- Track test coverage trends
- Monitor build times
- Alert on failures

### AI Agent Workflow

1. **Analyze:** Review current implementation and identify improvements
2. **Plan:** Create detailed implementation plan with alternatives
3. **Implement:** Make changes with proper testing
4. **Document:** Update ADRs and documentation
5. **Validate:** Ensure CI/CD passes and tests are updated

### Best Practices for AI Agents

- **Follow existing patterns** - Match project conventions
- **Update documentation** - Keep docs in sync with changes
- **Add tests** - Ensure new functionality is tested
- **Small increments** - Make focused, reviewable changes
- **Clear commit messages** - Use conventional commits format

## 🤝 Community

- **Issues**: Report bugs and request features
- **Discussions**: Ask questions and propose ideas
- **Contributions**: All contributions welcome!

## 📜 License

By contributing to dance-lessons-coach, you agree that your contributions will be licensed under the MIT License.

---

**Thank you for contributing!** 🎉
=======
## 🤖 AI Agent Contributions

AI agents play a crucial role in maintaining and improving dance-lessons-coach. This section provides guidance for AI agents on how to effectively contribute.

### Key Files and Directories

**Core System:**
- `cmd/server/main.go` - Main server entry point with swagger metadata
- `pkg/server/server.go` - Server implementation with `go:generate` directive
- `pkg/greet/` - Greet service implementation
- `.gitea/workflows/` - CI/CD workflows

**Documentation:**
- `adr/` - Architecture Decision Records
- `CONTRIBUTING.md` - Contribution guidelines
- `README.md` - Project overview

**Scripts:**
- `scripts/` - Utility scripts for development
- `.git/hooks/` - Git hooks for automation

### Skills to Use/Improve

**Existing Skills:**
- `bdd-testing` - Behavior-Driven Development testing
- `skill-creator` - Skill creation and management
- `gitea-client` - Gitea API interactions

**Skills to Develop:**
- `ci-cd-optimization` - CI/CD pipeline improvements
- `version-management` - Automatic version bumping
- `artifact-management` - Build artifact optimization
- `documentation-generation` - Automatic doc updates

### Continuous Improvement Areas

**CI/CD Pipeline:**
- Optimize job dependencies and artifact passing
- Improve version bumping logic based on commit analysis
- Enhance Docker build caching and layer optimization
- Add more comprehensive test coverage

**Code Quality:**
- Expand swag fmt integration to other comment types
- Add additional linting checks
- Improve test automation
- Enhance error handling patterns

**Documentation:**
- Auto-generate ADR templates
- Improve API documentation completeness
- Add more examples and tutorials
- Keep documentation in sync with code

**Monitoring:**
- Add CI/CD performance metrics
- Track test coverage trends
- Monitor build times
- Alert on failures

### AI Agent Workflow

1. **Analyze:** Review current implementation and identify improvements
2. **Plan:** Create detailed implementation plan with alternatives
3. **Implement:** Make changes with proper testing
4. **Document:** Update ADRs and documentation
5. **Validate:** Ensure CI/CD passes and tests are updated

### Best Practices for AI Agents

- **Follow existing patterns** - Match project conventions
- **Update documentation** - Keep docs in sync with changes
- **Add tests** - Ensure new functionality is tested
- **Small increments** - Make focused, reviewable changes
- **Clear commit messages** - Use conventional commits format

## 🤝 Community

- **Issues**: Report bugs and request features
- **Discussions**: Ask questions and propose ideas
- **Contributions**: All contributions welcome!

## 📜 License

By contributing to dance-lessons-coach, you agree that your contributions will be licensed under the MIT License.

---

**Thank you for contributing!** 🎉
## 📝 Naming Conventions

### Files
- Use kebab-case: `my-file-name.md`
- Include purpose: `bdd-feature-structure.md`
- Avoid generics: Not `status.md`, use `project-status.md`

### Directories
- Use kebab-case: `my-directory/`
- Group by feature: `epic_user-management/`
- Avoid nesting >3 levels deep (max: `features/epic/user-story/`)

### ADRs
- Sequential numbering: `0019-bdd-feature-structure.md`
- Clear titles: Describe the decision
- Consistent format: Follow ADR template

### Commits
- Use gitmoji: `:sparkles: feat`, `:bug: fix`, `:memo: docs`
- Reference issues: `Fixes #123` or `Related to #456`
- Keep concise: 50-72 characters