diff --git a/CHANGELOG.md b/CHANGELOG.md index 4c555f6..fd6e5d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -106,7 +106,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Better error messages for PITR operations ### Production -- **Deployed at uuxoi.local**: 2 production hosts +- **Production Validated**: 2 production hosts - **Databases backed up**: 8 databases nightly - **Retention policy**: 30-day retention with minimum 5 backups - **Backup volume**: ~10MB/night diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..baa2a5e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,296 @@ +# 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.1.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:** +``` +: + + + +