diff --git a/CONTRIBUTING_GUIDE.md b/CONTRIBUTING_GUIDE.md new file mode 100644 index 00000000..6cecf55e --- /dev/null +++ b/CONTRIBUTING_GUIDE.md @@ -0,0 +1,219 @@ +# ๐Ÿš€ 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](https://github.com/gin-gonic/gin/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +- Look for issues labeled "good first issue" or "help wanted" +- Browse [Discussions](https://github.com/gin-gonic/gin/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:** +```bash +# Create a new branch for your work +git checkout -b feature/my-contribution +``` + +**Make Your Changes:** +```bash +# 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:** +```bash +# 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:** +```go +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 +```bash +cd examples/ +go run /main.go +``` + +### Checking Code Coverage +```bash +make test +# coverage.out file will be generated +go tool cover -html=coverage.out +``` + +### Testing Against Different Go Versions +```bash +# The project supports Go 1.24+ +# Make sure your changes work with that version +``` + +### Debugging Tips +```bash +# 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](https://github.com/gin-gonic/gin/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:** +```bash +# 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. ๐Ÿ™Œ