# Contributing to dbbackup Thank you for your interest in contributing to dbbackup! This document provides guidelines and instructions for contributing. ## Code of Conduct Be respectful, constructive, and professional in all interactions. We're building enterprise software together. ## How to Contribute ### Reporting Bugs **Before submitting a bug report:** - Check existing issues to avoid duplicates - Verify you're using the latest version - Collect relevant information (version, OS, database type, error messages) **Bug Report Template:** ``` **Version:** dbbackup v3.2.0 **OS:** Linux/macOS/BSD **Database:** PostgreSQL 14 / MySQL 8.0 / MariaDB 10.6 **Command:** The exact command that failed **Error:** Full error message and stack trace **Expected:** What you expected to happen **Actual:** What actually happened ``` ### Feature Requests We welcome feature requests! Please include: - **Use Case:** Why is this feature needed? - **Description:** What should the feature do? - **Examples:** How would it be used? - **Alternatives:** What workarounds exist today? ### Pull Requests **Before starting work:** 1. Open an issue to discuss the change 2. Wait for maintainer feedback 3. Fork the repository 4. Create a feature branch **PR Requirements:** - ✅ All tests pass (`go test -v ./...`) - ✅ New tests added for new features - ✅ Documentation updated (README.md, comments) - ✅ Code follows project style - ✅ Commit messages are clear and descriptive - ✅ No breaking changes without discussion ## Development Setup ### Prerequisites ```bash # Required - Go 1.21 or later - PostgreSQL 9.5+ (for testing) - MySQL 5.7+ or MariaDB 10.3+ (for testing) - Docker (optional, for integration tests) # Install development dependencies go mod download ``` ### Building ```bash # Build binary go build -o dbbackup # Build all platforms ./build_all.sh # Build Docker image docker build -t dbbackup:dev . ``` ### Testing ```bash # Run all tests go test -v ./... # Run specific test suite go test -v ./tests/pitr_complete_test.go # Run with coverage go test -cover ./... # Run integration tests (requires databases) ./run_integration_tests.sh ``` ### Code Style **Follow Go best practices:** - Use `gofmt` for formatting - Use `go vet` for static analysis - Follow [Effective Go](https://golang.org/doc/effective_go.html) - Write clear, self-documenting code - Add comments for complex logic **Project conventions:** - Package names: lowercase, single word - Function names: CamelCase, descriptive - Variables: camelCase, meaningful names - Constants: UPPER_SNAKE_CASE - Errors: Wrap with context using `fmt.Errorf` **Example:** ```go // Good func BackupDatabase(ctx context.Context, config *Config) error { if err := validateConfig(config); err != nil { return fmt.Errorf("invalid config: %w", err) } // ... } // Avoid func backup(c *Config) error { // No context, unclear name, no error wrapping } ``` ## Project Structure ``` dbbackup/ ├── cmd/ # CLI commands (Cobra) ├── internal/ # Internal packages │ ├── backup/ # Backup engine │ ├── restore/ # Restore engine │ ├── pitr/ # Point-in-Time Recovery │ ├── cloud/ # Cloud storage backends │ ├── crypto/ # Encryption │ └── config/ # Configuration ├── tests/ # Test suites ├── bin/ # Compiled binaries ├── main.go # Entry point └── README.md # Documentation ``` ## Testing Guidelines **Unit Tests:** - Test public APIs - Mock external dependencies - Use table-driven tests - Test error cases **Integration Tests:** - Test real database operations - Use Docker containers for isolation - Clean up resources after tests - Test all supported database versions **Example Test:** ```go func TestBackupRestore(t *testing.T) { tests := []struct { name string dbType string size int64 expected error }{ {"PostgreSQL small", "postgres", 1024, nil}, {"MySQL large", "mysql", 1024*1024, nil}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { // Test implementation }) } } ``` ## Documentation **Update documentation when:** - Adding new features - Changing CLI flags - Modifying configuration options - Updating dependencies **Documentation locations:** - `README.md` - Main documentation - `PITR.md` - PITR guide - `DOCKER.md` - Docker usage - Code comments - Complex logic - `CHANGELOG.md` - Version history ## Commit Guidelines **Commit Message Format:** ``` :