Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
269 lines (199 loc) · 5.55 KB

CONTRIBUTING.md

File metadata and controls

269 lines (199 loc) · 5.55 KB

Contributing to Postgres Backup S3/R2

Thank you for your interest in contributing! This document provides guidelines and instructions for contributing.

🚀 Getting Started

Prerequisites

  • Bun >= 1.0
  • Docker and Docker Compose
  • PostgreSQL client tools (for local testing)
  • Access to S3/R2/S3-compatible storage (for integration testing)

Setup Development Environment

# Clone the repository
git clone https://github.com/johnnybui/postgres-backup-s3.git
cd postgres-backup-s3

# Install dependencies
bun install

# Copy environment example
cp env.example .env
# Edit .env with your configuration

# Run in development mode
bun run src/index.ts

🔨 Development Workflow

Project Structure

.
├── src/
│   └── index.ts          # Main TypeScript application
├── backup.sh             # Backup shell script
├── restore.sh            # Restore shell script
├── run.sh                # Entry point script
├── Dockerfile      # Docker build configuration
├── docker-compose.example.yml  # Example compose file
└── README.md         # Documentation

Making Changes

  1. Create a branch

    git checkout -b feature/your-feature-name

  2. Make your changes

    • TypeScript changes: src/index.ts
    • Shell scripts: backup.sh, restore.sh
    • Documentation: README.md

  3. Test your changes

    # Run locally
bun run src/index.ts

# Build Docker image
make build

# Test with Docker Compose
make run
make logs

  4. Test backup/restore

    # Test one-time backup
make test-backup

# List backups
make list-backups

# Test restore
make test-restore BACKUP_FILE=postgres/db_2025-10-06.sql.gz

Code Style

  • TypeScript: Follow standard TypeScript conventions
  • Shell scripts: Use shellcheck for linting
  • Formatting: Use Prettier for TypeScript
# Format code
make format

# Type check
make lint

🧪 Testing

Manual Testing Checklist

Before submitting a PR, test:

  • One-time backup works
  • Scheduled backup works (test with short interval)
  • Multiple database backup works
  • Parallel backup works
  • Restore works for each storage type:
    • AWS S3
    • Cloudflare R2
    • S3-Compatible (Minio)
  • Encryption/decryption works
  • Auto-cleanup works
  • Custom format backup/restore works

Testing with Different Storage Types

# Test with R2
STORAGE_TYPE=R2
R2_ACCOUNT_ID=your-id

# Test with Minio
STORAGE_TYPE=COMPATIBLE
S3_ENDPOINT=http://minio:9000

# Test with AWS S3
STORAGE_TYPE=S3
S3_REGION=us-west-1

📝 Documentation

  • Update README.md for user-facing changes
  • Update CHANGELOG.md following Keep a Changelog format
  • Add inline comments for complex logic
  • Update environment variable documentation

🐛 Bug Reports

When filing a bug report, include:

  • Environment details (OS, Docker version, etc.)
  • Configuration (sanitize sensitive data!)
  • Expected behavior
  • Actual behavior
  • Logs (with timestamps)
  • Steps to reproduce

✨ Feature Requests

For feature requests, please:

  • Check existing issues first
  • Describe the use case
  • Explain why it would be useful
  • Consider backward compatibility

🔀 Pull Request Process

  1. Fork the repository

  2. Create a feature branch

    git checkout -b feature/amazing-feature

  3. Commit your changes Follow the commit message format:

    feat: ✨ add parallel restore support

- Implement parallel restore using pg_restore -j
- Add PARALLEL_RESTORE_JOBS env var
- Update documentation

  4. Push to your fork

    git push origin feature/amazing-feature

  5. Open a Pull Request

    • Use a clear title
    • Reference any related issues
    • Describe what changed and why
    • Include testing steps

  6. Code Review

    • Address review comments
    • Keep the PR focused and small
    • Squash commits if requested

📋 Commit Message Guidelines

Use conventional commits:

type(scope): emoji description

- Detailed change 1
- Detailed change 2

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • refactor: Code refactoring
  • chore: Maintenance tasks
  • test: Test changes

Examples:

feat(storage): ✨ add Oracle Cloud support
fix(backup): 🐛 fix encryption for custom format
docs: 📝 add DigitalOcean Spaces example
refactor(shell): ♻️ simplify storage type detection
chore(deps): ⬆️ update bun to 1.1.0

🏗️ Building Docker Images

Local Build

make build

Multi-platform Build

docker buildx build --platform linux/amd64,linux/arm64 \
  -f Dockerfile \
  -t ghcr.io/johnnybui/postgres-backup-s3:latest .

Testing Built Image

docker run --rm \
  -e POSTGRES_DATABASE=test \
  -e POSTGRES_HOST=localhost \
  ghcr.io/johnnybui/postgres-backup-s3:latest

🔒 Security

  • Never commit credentials or secrets
  • Use .env for local configuration
  • Report security issues privately (see SECURITY.md if exists)
  • Keep dependencies updated

📜 License

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

🙏 Thank You

Your contributions make this project better for everyone. Thank you for taking the time to contribute!

💬 Questions?

  • Open an issue for questions
  • Check existing issues and discussions
  • Read the documentation thoroughly

Happy coding! 🚀