feat: integrate swag fmt and improve CI/CD workflows
Some checks failed
Go CI/CD Pipeline / Lint and Format (push) Successful in 4m51s
Docker Build and Publish / Version Bump (push) Successful in 4m54s
Docker Build and Publish / Build and Push Docker Image (push) Failing after 2m51s
Go CI/CD Pipeline / Build and Test (push) Successful in 9m47s
Go CI/CD Pipeline / Version Management (push) Successful in 12s
Some checks failed
Go CI/CD Pipeline / Lint and Format (push) Successful in 4m51s
Docker Build and Publish / Version Bump (push) Successful in 4m54s
Docker Build and Publish / Build and Push Docker Image (push) Failing after 2m51s
Go CI/CD Pipeline / Build and Test (push) Successful in 9m47s
Go CI/CD Pipeline / Version Management (push) Successful in 12s
- Add swag fmt to git pre-commit hook and CI/CD pipeline - Create comprehensive CONTRIBUTING.md guide with AI section - Update ADR-0013 with swag fmt documentation - Fix swagger generation to include all endpoints - Improve local testing scripts and workflows - Update Dockerfile for better swagger handling - Fix CI/CD workflow file references
This commit is contained in:
439
CONTRIBUTING.md
Normal file
439
CONTRIBUTING.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# Contributing to DanceLessonsCoach
|
||||
|
||||
Thank you for your interest in contributing to DanceLessonsCoach! 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/DanceLessonsCoach.git
|
||||
cd DanceLessonsCoach
|
||||
|
||||
# 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 DanceLessonsCoach. 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 DanceLessonsCoach, 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 DanceLessonsCoach. 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 DanceLessonsCoach, you agree that your contributions will be licensed under the MIT License.
|
||||
|
||||
---
|
||||
|
||||
**Thank you for contributing!** 🎉
|
||||
Reference in New Issue
Block a user