dbbackup/CONTRIBUTING.md

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.40.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

# 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

# Build binary
go build -o dbbackup

# Build all platforms
./build_all.sh

# Build Docker image
docker build -t dbbackup:dev .

Testing

# 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
• 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:

// 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:

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:

<type>: <subject>

<body>

<footer>

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style changes (formatting)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples:

feat: Add Azure Blob Storage backend

Implements Azure Blob Storage backend for cloud backups.
Includes streaming upload/download and metadata preservation.

Closes #42

---

fix: Handle MySQL connection timeout gracefully

Adds retry logic for transient connection failures.
Improves error messages for timeout scenarios.

Fixes #56

Pull Request Process

1. Create Feature Branch

   git checkout -b feature/my-feature
   

2. Make Changes

   • Write code
   • Add tests
   • Update documentation

3. Commit Changes

   git add -A
   git commit -m "feat: Add my feature"
   

4. Push to Fork

   git push origin feature/my-feature
   

5. Open Pull Request

   • Clear title and description
   • Reference related issues
   • Wait for review

6. Address Feedback

   • Make requested changes
   • Push updates to same branch
   • Respond to comments

7. Merge

   • Maintainer will merge when approved
   • Squash commits if requested

Release Process (Maintainers)

1. Update version in main.go
2. Update CHANGELOG.md
3. Commit: git commit -m "Release vX.Y.Z"
4. Tag: git tag -a vX.Y.Z -m "Release vX.Y.Z"
5. Push: git push origin main vX.Y.Z
6. Build binaries: ./build_all.sh
7. Create GitHub Release with binaries

Questions?

• Issues: https://git.uuxo.net/PlusOne/dbbackup/issues
• Discussions: Use issue tracker for now
• Email: See SECURITY.md for contact

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.

---

Thank you for contributing to dbbackup! 🎉