gin/CONTRIBUTING_GUIDE.md

🚀 Quick Start Guide to Contributing to Gin

Welcome! This guide will help you get started contributing to the Gin Web Framework.

✅ Environment Setup Complete

Your development environment is ready:

• Go Version: 1.25.0 ✓ (requires 1.24+)
• Dependencies: All modules verified ✓
• Dev Tools: golint and misspell installed ✓
• Tests: All passing (99.1% coverage) ✓

📚 Understanding the Project Structure

Core Files

• gin.go - Main engine and router
• context.go - Request/response context handling
• routergroup.go - Route grouping and middleware
• tree.go - High-performance routing tree (radix tree)
• logger.go - Logging middleware
• recovery.go - Panic recovery middleware

Important Directories

• binding/ - Request data binding (JSON, XML, YAML, forms, etc.)
• render/ - Response rendering (JSON, XML, HTML, etc.)
• internal/ - Internal utilities (not public API)
• examples/ - Usage examples

🎯 How to Contribute

1. Find Something to Work On

Good First Issues:

• Check GitHub Issues
• Look for issues labeled "good first issue" or "help wanted"
• Browse Discussions for feature ideas

Areas You Can Help:

• 🐛 Fix bugs
• 📝 Improve documentation in docs/doc.md
• ✨ Add new features
• 🧪 Improve test coverage
• ⚡ Performance optimizations
• 🌐 Translate documentation

2. Development Workflow

Before Starting:

# Create a new branch for your work
git checkout -b feature/my-contribution

Make Your Changes:

# Format your code (required)
make fmt

# Run tests
make test

# Check for common issues
make vet

# Check formatting (CI will run this)
make fmt-check

# Fix misspellings
make misspell

Run Specific Tests:

# Test a specific package
go test -v ./binding/

# Test a specific function
go test -v -run TestContextQuery

# Run with race detector
go test -race ./...

3. Code Standards

Important Rules:

• ✅ All tests must pass
• ✅ Code must be formatted with make fmt
• ✅ Add tests for new features
• ✅ Update docs/doc.md for new features (NOT README.md)
• ✅ Keep commits focused and atomic
• ✅ Squash to max 2 commits before submitting PR

Example Test Pattern:

func TestMyNewFeature(t *testing.T) {
    // Setup
    router := gin.New()
    
    // Test your feature
    w := httptest.NewRecorder()
    req, _ := http.NewRequest("GET", "/test", nil)
    router.ServeHTTP(w, req)
    
    // Assert
    assert.Equal(t, 200, w.Code)
}

4. Submit Your PR

Checklist:

• Tests pass locally (make test)
• Code is formatted (make fmt)
• No linting errors (make vet)
• Documentation updated (if needed)
• Commits squashed to ≤2 commits
• PR targets master branch
• PR description explains what and why

PR Template Will Ask:

• What does this PR do?
• Why is this change needed?
• How has this been tested?
• What issues does it fix? (use Fixes #123)

🛠️ Common Development Tasks

Running the Examples

cd examples/
go run <example-name>/main.go

Checking Code Coverage

make test
# coverage.out file will be generated
go tool cover -html=coverage.out

Testing Against Different Go Versions

# The project supports Go 1.24+
# Make sure your changes work with that version

Debugging Tips

# Enable debug mode
export GIN_MODE=debug

# Run with verbose output
go test -v -run TestName

📖 Key Resources

• API Docs: https://pkg.go.dev/github.com/gin-gonic/gin
• User Guides: https://gin-gonic.com/
• Discussions: https://github.com/gin-gonic/gin/discussions
• Examples: https://github.com/gin-gonic/examples

🤔 Getting Help

Questions?

• Post in GitHub Discussions
• Use English for all communications
• Search existing issues/discussions first

Security Issues?

• Email: appleboy.tw@gmail.com
• Do NOT post publicly

💡 Contribution Ideas for Beginners

1. Documentation Improvements

   • Fix typos or unclear explanations
   • Add code examples
   • Improve error messages

2. Test Coverage

   • Add tests for edge cases
   • Improve test clarity

3. Performance Benchmarks

   • Add benchmarks for new features
   • Run: go test -bench=. -benchmem

4. Code Quality

   • Simplify complex functions
   • Add helpful comments
   • Improve error handling

🎉 Ready to Contribute!

Quick Command Reference:

# Check everything before submitting
make fmt         # Format code
make test        # Run tests
make vet         # Check for issues
make misspell    # Fix spelling

# Or check formatting without changing files
make fmt-check
make misspell-check

Next Steps:

1. Browse issues or discussions for ideas
2. Comment on an issue to claim it
3. Create your branch and start coding
4. Run the checks above
5. Submit your PR!

---

Thank you for contributing to Gin! Every contribution, no matter how small, helps make Gin better for the entire community. 🙌