Fix Bug

Fix Bug

TDD workflow for fixing bugs from GitHub issues: reproduce first, then fix, then verify.

Two principles to keep turnaround fast:

1. Run only the impacted/relevant tests locally — never the full suite. CI runs the full suite on the PR; locally you only need to confirm the reproducing test and its immediate neighbors. Narrow PGSCHEMA_TEST_FILTER to the specific case (or category) you touched.
2. Prefer folding testdata/diff cases into existing ones — each test case is its own embedded-postgres apply cycle, so every new directory adds to total test time. By default, consider adding the scenario to a related existing case. Only create a new case when that's more reasonable or consistent with the existing layout (see Phase 2).

Phase 1: Analyze

1. Fetch the issue: gh issue view <number>
2. Classify the bug:
   • Dump bug: pgschema dump produces wrong output → test in testdata/dump/
   • Diff/Plan bug: dump is correct but plan generates wrong DDL → test in testdata/diff/
   • Both: start with dump; if dump is correct, it's a diff bug

Phase 2: Create Test Case (Red)

Dump Bugs

Create testdata/dump/issue_<N>_<description>/ with:

• manifest.json — metadata with name, description, source URL, notes
• raw.sql — original DDL
• pgdump.sql — what pg_dump produces (input to test)
• pgschema.sql — expected correct output

Register in cmd/dump/dump_integration_test.go:

func TestDumpCommand_Issue<N><Description>(t *testing.T) {
    if testing.Short() { t.Skip("Skipping integration test in short mode") }
    runExactMatchTest(t, "issue_<N>_<description>")
}

Verify it fails: go test -v ./cmd/dump -run TestDumpCommand_Issue<N>

Diff/Plan Bugs

Categories: create_table, create_index, create_trigger, create_view, create_function, create_procedure, create_sequence, create_type, create_domain, create_policy, create_materialized_view, comment, privilege, default_privilege, dependency, online, migrate.

Decide: fold or create new (default: consider folding). Each case directory is a separate embedded-postgres apply cycle, so folding keeps the suite fast.

• Fold when the bug is a natural variation of an existing case (same object type/category) and adding the DDL doesn't obscure that case's intent. Add the reproducing statements to the existing old.sql/new.sql, then regenerate its expected outputs. Browse the category first (ls testdata/diff/<category>/) to find the best home.
• Create new (testdata/diff/<category>/issue_<N>_<description>/ with old.sql and new.sql) when the scenario is distinct, or when a standalone issue_<N> case is more consistent with how the category is organized.

Verify it fails (use the case name you folded into, or the new issue_<N>_<description>):

PGSCHEMA_TEST_FILTER="<category>/<case>" go test -v ./internal/diff -run TestDiffFromFiles

Generate expected outputs once you know correct behavior:

PGSCHEMA_TEST_FILTER="<category>/<case>" go test -v ./cmd -run TestPlanAndApply --generate

Phase 3: Fix (Green)

Common locations:

• Dump: ir/inspector.go, ir/normalize.go, internal/dump/
• Diff: internal/diff/ (table.go, column.go, index.go, trigger.go, view.go, function.go, procedure.go, sequence.go, type.go, policy.go, constraint.go)
• IR: ir/ir.go, ir/quote.go

Make the minimal fix. Use pg_dump and postgres_syntax skills as needed.

Phase 4: Verify

Run only the impacted tests (not the full suite — CI runs that on the PR). Keep the filter as narrow as possible:

# Dump bugs
go test -v ./cmd/dump -run TestDumpCommand_Issue<N>

# Diff bugs — start with the specific case
PGSCHEMA_TEST_FILTER="<category>/<case>" go test -v ./internal/diff -run TestDiffFromFiles
PGSCHEMA_TEST_FILTER="<category>/<case>" go test -v ./cmd -run TestPlanAndApply

Only widen the filter to the whole category (PGSCHEMA_TEST_FILTER="<category>/") if the fix touched shared diff logic that could affect sibling cases.

Phase 5: Create PR

git checkout -b fix/issue-<N>-<description>
git add <files>
git commit -m "fix: <description> (#<N>)"
git push -u origin fix/issue-<N>-<description>
gh pr create --title "fix: <description> (#<N>)" --body "## Summary
<what was broken and how it was fixed>

Fixes #<N>

## Test plan
<what test was added and how to run it>"

Checklist

• Bug classified (dump vs diff)
• Test case folded into an existing case, or new issue_<N>_<description> created when more reasonable
• Test fails before fix (red)
• Minimal fix implemented
• Test passes after fix (green)
• Impacted tests pass locally (narrow filter — full suite left to CI)
• PR created and linked to issue