# Contributing to GoSQLX Thank you for your interest in contributing to GoSQLX! This document provides comprehensive guidelines for contributing to the project. ## Project Mission GoSQLX aims to be the **fastest, most reliable, and most comprehensive SQL parsing library for Go**, suitable for production use in enterprise environments. ## Ways to Contribute ### 1. Code Contributions - **Bug fixes**: Resolve issues in tokenization, parsing, or performance - **Feature development**: Implement new SQL dialect support or optimizations - **Performance improvements**: Optimize hot paths and memory usage - **Test coverage**: Add comprehensive tests for edge cases ### 2. Documentation - **API documentation**: Improve godoc coverage and examples - **Tutorials**: Create guides for specific use cases - **Performance guides**: Document optimization techniques - **Integration examples**: Add real-world usage examples ### 3. Testing & Quality Assurance - **Bug reports**: Report issues with detailed reproduction steps - **Performance testing**: Benchmark new features and optimizations - **Security testing**: Identify potential vulnerabilities - **Compatibility testing**: Test across different Go versions and platforms ### 4. Community Support - **Answer questions**: Help users in GitHub Issues and Discussions - **Code reviews**: Review pull requests from other contributors - **Feature discussions**: Participate in RFC discussions for new features --- ## Development Setup ### Prerequisites - **Go 1.21+** (latest stable version recommended) - **Git** for version control - **Task** for task automation (optional) - Install with `go install github.com/go-task/task/v3/cmd/task@latest` ### Getting Started ```bash # 1. Fork the repository on GitHub # 2. Clone your fork git clone https://github.com/YOUR_USERNAME/GoSQLX.git cd GoSQLX # 3. Add upstream remote git remote add upstream https://github.com/ajitpratap0/GoSQLX.git # 4. Install dependencies go mod download # 5. Run tests to verify setup go test ./... # 6. Run tests with race detection (REQUIRED) go test -race ./... # 7. Install Git hooks (RECOMMENDED) task hooks:install # or ./scripts/install-hooks.sh ``` ### Installing Git Hooks GoSQLX provides pre-commit hooks to catch code quality issues before they reach CI/CD: ```bash # Install hooks using Task task hooks:install # Or run the script directly ./scripts/install-hooks.sh ``` The pre-commit hooks automatically run: - **go fmt**: Checks code formatting - **go vet**: Performs static analysis - **go test -short**: Runs tests in short mode To bypass hooks (not recommended): ```bash git commit --no-verify ``` ### Development Workflow ```bash # 1. Create a feature branch git checkout -b feature/your-feature-name # 2. Make your changes # ... edit files ... # 3. Run tests frequently go test -race ./... # 4. Run linting and formatting go fmt ./... go vet ./... # 5. Commit your changes git add . git commit -m "feat: add support for PostgreSQL JSON operators" # 6. Push to your fork git push origin feature/your-feature-name # 7. Create a Pull Request ``` --- ## Contribution Guidelines ### Code Quality Standards #### Testing Requirements - **100% test coverage** for new code (use `go test -cover`) - **Race detection** must pass: `go test -race ./...` - **Performance tests** for optimization changes - **Integration tests** for new SQL features ```go // Example: Comprehensive test structure func TestNewFeature(t *testing.T) { tests := []struct { name string input string expected interface{} wantErr bool }{ {"valid case", "SELECT * FROM users", expectedTokens, false}, {"edge case", "", nil, true}, {"unicode", "SELECT 名前 FROM ユーザー", expectedUnicodeTokens, false}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { // Test implementation }) } } // Benchmark for performance-sensitive code func BenchmarkNewFeature(b *testing.B) { for i := 0; i < b.N; i++ { // Benchmark implementation } } ``` #### Code Style - **Go fmt**: All code must be formatted with `go fmt` - **Go vet**: Must pass `go vet` without warnings - **Golint**: Follow Go naming conventions - **Comments**: Public functions require godoc comments ```go // ✅ GOOD: Proper function documentation // TokenizeSQL parses the provided SQL query and returns a slice of tokens. // It supports multiple SQL dialects and provides detailed error information. // // The input must be valid UTF-8. Large queries (>1MB) may impact performance. // // Example: // tokens, err := TokenizeSQL([]byte("SELECT * FROM users")) // if err != nil { // return fmt.Errorf("tokenization failed: %w", err) // } func TokenizeSQL(sql []byte) ([]Token, error) { // Implementation } // ❌ BAD: Missing documentation func TokenizeSQL(sql []byte) ([]Token, error) { // Implementation } ``` #### Security Guidelines - **Input validation**: Always validate external input - **Memory safety**: Use Go's memory safety features correctly - **Resource limits**: Implement bounds checking for large inputs - **Error handling**: Never leak sensitive information in error messages ```go // ✅ GOOD: Proper input validation and error handling func ProcessSQL(sql []byte) error { if len(sql) > MaxSQLSize { return errors.New("SQL query too large") } if !utf8.Valid(sql) { return errors.New("invalid UTF-8 input") } // Safe processing return nil } // ❌ BAD: No input validation func ProcessSQL(sql []byte) error { // Direct processing without validation } ``` ### Performance Requirements #### Performance Standards - **No performance regression**: New features must not slow down existing functionality - **Memory efficiency**: Minimize allocations in hot paths - **Concurrency safety**: All public APIs must be thread-safe - **Benchmarking**: Include benchmarks for performance-critical code ```go // Example: Memory-efficient implementation func OptimizedFunction() { // ✅ GOOD: Reuse objects tkz := tokenizer.GetTokenizer() defer tokenizer.PutTokenizer(tkz) // ❌ BAD: Creates new objects repeatedly // tkz := &tokenizer.Tokenizer{} } ``` ### Git Commit Guidelines #### Commit Message Format ``` ():