Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
83 lines (59 loc) · 2.51 KB

CONTRIBUTING.md

File metadata and controls

83 lines (59 loc) · 2.51 KB

Contributing to pgcopycat

Thanks for considering a contribution to pgcopycat.

This project is intended to stay practical, readable, and safe for local PostgreSQL refresh workflows. Contributions that improve correctness, safety, usability, documentation, and test coverage are especially welcome.

Before You Start

  • Read the current README.md
  • Check whether the change fits the project scope
  • Prefer opening an issue first for large features or behavior changes
  • For security-sensitive issues, follow SECURITY.md instead of creating a public issue immediately

Development Setup

Requirements:

  • Go 1.25+
  • PostgreSQL client tools in PATH
    • pg_dump
    • pg_restore
    • psql

Build locally:

go build -o pgcopycat ./cmd/pgcopycat

Run tests:

go test ./...

Repository Structure

  • cmd/pgcopycat/: CLI entrypoint
  • internal/config/: config parsing and validation
  • internal/discovery/: profile discovery
  • internal/planner/: execution plan construction
  • internal/checks/: pre-flight checks
  • internal/postgres/: PostgreSQL inspection and SQL helpers
  • internal/runner/: dump and restore orchestration
  • internal/report/: final report rendering
  • internal/ui/: interactive prompt flows

Pull Request Guidelines

  • Keep changes focused and easy to review
  • Add or update tests when behavior changes
  • Update documentation when commands, config, prompts, or safety behavior change
  • Preserve the project’s guard rails around destructive operations
  • Avoid introducing role or ACL restoration behavior unless it is intentionally discussed and approved

Please include in your pull request:

  • A short summary of the problem
  • The approach you chose
  • Any tradeoffs or limitations
  • Test coverage or manual validation notes

Coding Expectations

  • Prefer clear, maintainable code over clever shortcuts
  • Keep user-facing messages explicit and actionable
  • Preserve interactive and non-interactive behavior where relevant
  • Be careful around passwords, config persistence, and anything destructive on the destination database

Documentation Expectations

If your change affects any of the following, update the docs in the same pull request:

  • Commands or flags
  • Config structure
  • Interactive prompts
  • Safety defaults
  • Extension or sequence behavior
  • Open-source contribution guidance

Questions

If you are unsure whether an idea belongs in pgcopycat, open an issue or draft pull request and explain the use case before investing heavily in implementation.