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
2. Code Style
3. Commit Process
4. Testing
5. Documentation
6. Pull Request Process

🔧 Development Setup

Prerequisites

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

Installation

# 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:

chmod +x .git/hooks/pre-commit

🎨 Code Style

Go Formatting

We use go fmt for Go code formatting:

go fmt ./...

Swagger Formatting

We use swag fmt to format swagger comments:

swag fmt

This is automatically run in:

• Pre-commit hook
• CI/CD lint-format job

Commit Messages

We follow Conventional Commits:

# 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

   go test ./...
   

2. Format code: Run formatting tools

   go fmt ./...
   swag fmt
   

3. Build project: Ensure it compiles

   go build ./...
   

4. Generate docs: Update swagger documentation

   cd pkg/server && go generate
   

Making Changes

1. Create a branch: Use a descriptive name

   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

   git add .
   git commit -m "feat: add new feature"
   

4. Push: Push to your fork or branch

   git push origin feat/add-new-feature
   

🧪 Testing

Unit Tests

# Run all tests
go test ./...

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

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

Integration Tests

# 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

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

📚 Documentation

Swagger Documentation

We use swaggo for API documentation:

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

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

Adding Swagger Comments

// @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-0002: Chi Router
• ADR-0003: Zerolog Logging
• ADR-0013: OpenAPI/Swagger Toolchain

🤖 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