Félix Malfait
38fbff465f
Follow-up to #22417, per [this thread](https://github.com/twentyhq/twenty/pull/22417#discussion_r3512187719): migrate the `2-20/README.md` placeholder into a real command using the `TWENTY_NEXT_VERSIONS` mechanism. ### What - Add `DropMetadataStandardOverridesColumnFastInstanceCommand`, registered against `2.20.0`. It boots (`2.20.0` is in `TWENTY_ALL_VERSIONS`) but stays **dormant** — the upgrade sequence only runs `TWENTY_CROSS_UPGRADE_SUPPORTED_VERSIONS` (previous + current), so it never executes during the 2.19 deploy and activates automatically when `nx version:bump` promotes 2.20 to current. - Name constant + unit test (SQL parity, registration against `2.20.0`, name-constant parity). - Register it in `instance-commands.constant.ts`. - Update the `standardOverrides` `@deprecated` comments on object/field metadata to point at the shipped command. - Delete `2-20/README.md`. - Document the "ship a command for a future version" flow in `docs/UPGRADE_COMMANDS.md` and `.cursor/rules/server-migrations.mdc` (the mechanism was previously undocumented). ### Note / correction to the README's plan The old README implied both the command **and** `@WasRemovedInUpgrade` could be added at 2.20 time. Only the command can ship now: the decorator's validator runs against the active sequence, so referencing a still-dormant 2.20 step fails boot with `unknown-step-name`. So the entity keeps its `WasRemovedInUpgrade<T>` type wrapper for now; the decorator gets wired (one line, via the name constant) once 2.20 is current — same deferred-drop shape as `isUIReadOnly`. ### Verification Could not run `jest`/`typecheck`/`lint` in this environment: `yarn install` is blocked by egress policy on a git-based transitive dep (`github.com/electron/node-gyp.git`). Verified by review against the sibling 2-19 add-column and 2-12 drop commands. **Please let CI run before merge.** https://claude.ai/code/session_01KMArJvdEmsX3eAmJLbS1b6 --- _Generated by [Claude Code](https://claude.ai/code/session_01KMArJvdEmsX3eAmJLbS1b6)_ <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22448?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. -->
49 lines
2.7 KiB
Plaintext
49 lines
2.7 KiB
Plaintext
---
|
|
description: Guidelines for generating and managing upgrade commands (instance commands and workspace commands) in twenty-server
|
|
globs: [
|
|
"packages/twenty-server/src/**/*.entity.ts",
|
|
"packages/twenty-server/src/database/commands/upgrade-version-command/**/*.ts"
|
|
]
|
|
alwaysApply: false
|
|
---
|
|
|
|
## Upgrade Commands (twenty-server)
|
|
|
|
The upgrade system uses two types of commands instead of raw TypeORM migrations:
|
|
- **Instance commands** — schema and data migrations that run once at the instance level.
|
|
- **Workspace commands** — commands that iterate over all active/suspended workspaces.
|
|
|
|
See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation.
|
|
|
|
### Instance Commands
|
|
|
|
- **When changing a `*.entity.ts` file**, generate an instance command:
|
|
|
|
```bash
|
|
npx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>
|
|
```
|
|
|
|
- **Fast commands** (`--type fast`, default) are for schema-only changes that must run immediately. They implement `FastInstanceCommand` with `up`/`down` methods and use the `@RegisteredInstanceCommand` decorator.
|
|
|
|
- **Slow commands** (`--type slow`) add a `runDataMigration` method for potentially long-running data backfills that execute before `up`. They only run when `--include-slow` is passed. Use the decorator with `{ type: 'slow' }`.
|
|
|
|
- The generator auto-registers the command in `instance-commands.constant.ts` — do not edit that file manually.
|
|
|
|
- **Keep commands consistent and reversible**: include both `up` and `down` logic. Do not delete or rewrite existing, committed commands unless on a pre-release branch.
|
|
|
|
- **Shipping a command for a future version (deferred drops)**: pass `--version <next-version>` (a `TWENTY_NEXT_VERSIONS` value) to the generator to write a command that registers but stays dormant until `nx version:bump` makes that version current — e.g. dropping a column one release after its replacement ships. Caveat: `@WasRemovedInUpgrade`/`@WasIntroducedInUpgrade` reject a still-dormant next-version command at boot (`unknown-step-name`), so keep the entity's `WasRemovedInUpgrade<T>` type wrapper and add the decorator only once the version is current. See `docs/UPGRADE_COMMANDS.md`.
|
|
|
|
### Workspace Commands
|
|
|
|
- Use the `@RegisteredWorkspaceCommand` decorator alongside nest-commander's `@Command` decorator.
|
|
- Extend `ActiveOrSuspendedWorkspaceCommandRunner` and implement `runOnWorkspace`.
|
|
- The base class provides `--dry-run`, `--verbose`, and workspace filter options automatically.
|
|
|
|
### Execution Order
|
|
|
|
Within a given version, commands run in this order (timestamp-sorted within each group):
|
|
1. Instance fast commands
|
|
2. Instance slow commands (only with `--include-slow`)
|
|
3. Workspace commands
|
|
|