Skip to content

docs(migration): note that t.timestamps() also adds deletedAt (#2313)#2362

Merged
bpamiri merged 1 commit intodevelopfrom
peter/docs-timestamps-three-columns
Apr 29, 2026
Merged

docs(migration): note that t.timestamps() also adds deletedAt (#2313)#2362
bpamiri merged 1 commit intodevelopfrom
peter/docs-timestamps-three-columns

Conversation

@bpamiri
Copy link
Copy Markdown
Collaborator

@bpamiri bpamiri commented Apr 29, 2026

Summary

Why docs and not opt-in

The issue explicitly recommends the docs path:

Make the soft-delete column opt-in (t.timestamps(softDelete=true)), or update the docs to accurately describe the three-column behavior. (Note: the project's own CLAUDE.md anti-pattern #7 already documents the three-column behavior, so the docs side may be the right move.)

Making the soft-delete column opt-in would silently change the migration output for every existing Wheels app on disk — a backward-compat break for cosmetic gain. Documenting the existing behavior is the right move.

Files changed

File Before After
using-sqlite.md // Creates createdAt and updatedAt as TEXT // Creates createdAt, updatedAt, and deletedAt as TEXT
cli-guides/migrations.md // Creates createdAt and updatedAt // Creates createdAt, updatedAt, and deletedAt (soft-delete marker)
commands/generate/migration.md (table row) Creates createdAt and updatedAt Creates createdAt, updatedAt, and deletedAt (soft-delete marker)

Test plan

  • No code paths touched — pure doc fix.
  • Wording matches the existing accurate references in v4-0-0-snapshot/glossary.mdx and v4-0-0-snapshot/basics/migrations.mdx.

Three v3-0-0 doc spots described `t.timestamps()` as creating only
`createdAt` and `updatedAt`. The actual implementation in
`vendor/wheels/migrator/TableDefinition.cfc:372` adds three columns —
the third is `deletedAt`, the soft-delete marker.

The v4-0-0-snapshot guide and the v3 database-migrations index already
document the three-column behavior, and CLAUDE.md anti-pattern #7 calls
this out for code generators. This PR fixes the remaining v3-0-0
references so users reading any of these pages get a consistent picture.

Issue #2313 explicitly recommends the docs path here ("the project's own
CLAUDE.md anti-pattern #7 already documents the three-column behavior,
so the docs side may be the right move") rather than making the soft-
delete column opt-in, which would be a backward-compat break for every
existing app on disk.
@bpamiri bpamiri merged commit 4abff1a into develop Apr 29, 2026
9 checks passed
@github-actions github-actions Bot added the docs label Apr 29, 2026
@bpamiri bpamiri deleted the peter/docs-timestamps-three-columns branch April 29, 2026 15:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant