chore(db): collapse Drizzle migration snapshot diffs and block auto-merge (#11240)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip stores its state in a Postgres database, managed in
`packages/db`.
> - The schema uses Drizzle. `drizzle-kit` writes a full-schema snapshot
to `packages/db/src/migrations/meta/` for every migration.
> - Each snapshot is a large generated JSON file. One snapshot is over
200 KB.
> - GitHub shows these files as 30k+ line diffs in a pull request. The
diffs add no review value, because a human never edits the files.
> - The files also merge badly. `drizzle-kit` computes the `id`/`prevId`
chain and the full schema state, so a line-level merge of two snapshots
produces a file that no real `generate` run creates.
> - This pull request adds a `.gitattributes` file that marks the
snapshot directory as generated and blocks its auto-merge.
> - The benefit is clean pull request diffs and a loud conflict that
forces the correct fix when two branches add a migration.

## Linked Issues or Issue Description

No existing issue. This is a small repository-hygiene change.
Description follows the enhancement template:

**Problem / Motivation**
Every migration adds a full-schema snapshot JSON under
`packages/db/src/migrations/meta/`. These files are large and generated.
GitHub renders them as 30k+ line diffs in pull requests, which buries
the real change (the `.sql` migration) in noise. The files also have no
meaningful line-level merge: `drizzle-kit` computes each snapshot's
`id`/`prevId` chain and full schema state.

**Proposed Solution**
Add `packages/db/.gitattributes`:
- `linguist-generated=true` on `src/migrations/meta/**` — GitHub
collapses the diff and drops the files from language stats.
- `-merge` on the same glob — git refuses the line-level merge and
raises a conflict instead of fabricating an invalid snapshot.

**Alternatives Considered**
- `-diff` / `binary`: hides the diff completely and blocks text merge,
but also blocks any local `git diff` and gives a worse conflict
experience. `linguist-generated` keeps the file expandable and
text-based, so it is the lighter option.
- Do nothing: leaves the noisy diffs and the risk of a silent bad merge.

## What Changed

- Added `packages/db/.gitattributes`.
- Marked `src/migrations/meta/**` as `linguist-generated=true` to
collapse the snapshot and journal diffs on GitHub.
- Set `-merge` on the same files so git raises a conflict instead of
auto-merging generated snapshots.
- Left the `.sql` migration files untouched, so their diffs stay visible
for review.

## Verification

Run `git check-attr` against the affected files and a control `.sql`
file:

```
git check-attr linguist-generated merge -- \
  packages/db/src/migrations/meta/0031_snapshot.json \
  packages/db/src/migrations/meta/_journal.json \
  packages/db/src/migrations/0009_fast_jackal.sql
```

Expected output:

```
packages/db/src/migrations/meta/0031_snapshot.json: linguist-generated: true
packages/db/src/migrations/meta/0031_snapshot.json: merge: unset
packages/db/src/migrations/meta/_journal.json: linguist-generated: true
packages/db/src/migrations/meta/_journal.json: merge: unset
packages/db/src/migrations/0009_fast_jackal.sql: linguist-generated: unspecified
packages/db/src/migrations/0009_fast_jackal.sql: merge: unspecified
```

The snapshot and journal files carry both attributes. The `.sql`
migration keeps its normal diff and merge behavior. GitHub applies the
rule from the pull request tree, so the collapse shows on the next pull
request that touches these files.

## Risks

Low risk. The change only affects git and GitHub display and merge
behavior for generated files. It does not touch application code, the
schema, or any migration.

- `-merge` leaves the current-branch version in the working tree on
conflict and marks the file conflicted. It does not insert conflict
markers into the JSON. The correct resolution stays "renumber the later
migration and regenerate", then commit.
- Related open pull requests #879 and #8922 also add `.gitattributes`
rules for migration files, but for CRLF/LF hash mismatches on Windows.
If either lands, a follow-up can merge the rules into one file. There is
no functional overlap with this change.

## Model Used

Claude Opus 4.8 (Anthropic), model ID `claude-opus-4-8`, used through
Claude Code with extended thinking and tool use.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass — not applicable; this
change touches no code path, only git/GitHub file handling
- [x] I have added or updated tests where applicable — not applicable;
`.gitattributes` behavior is verified with `git check-attr` (see
Verification)
- [x] I have updated relevant documentation to reflect my changes — not
applicable; the `.gitattributes` file documents its own rules inline
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Nicky Leach 2026-08-11 16:59:03 -07:00 committed by GitHub
parent 3b74ff4813
commit c0bdf26633
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 10 additions and 0 deletions

10
packages/db/.gitattributes vendored Normal file
View File

@ -0,0 +1,10 @@
# Drizzle-generated migration snapshots + journal. Regenerated by
# `drizzle-kit generate`, never hand-edited. Two branches that each add a
# migration produce divergent snapshots (and journal entries) that CANNOT be
# meaningfully text-merged — the id/prevId chain and schema state are computed,
# so a line-level merge yields a snapshot matching no real `generate` run. The
# only correct resolution is to renumber one migration and regenerate. Hence:
# linguist-generated=true GitHub collapses the huge diff, excludes from stats
# -merge git refuses to auto-merge and raises a loud conflict
# instead of silently fabricating a bogus snapshot
src/migrations/meta/** linguist-generated=true -merge