first commit

.agents/skills/create-database-migration/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: Create database migration
+description: Create a database migration to add a table, add columns to an existing table, add a setting, or otherwise change the schema of Ghost's MySQL database. Use this skill whenever the task involves modifying Ghost's database schema — including adding, removing, or renaming columns or tables, adding new settings, creating indexes, updating data, or any change that requires a migration file in ghost/core. Also use when the user references schema.js, knex-migrator, the migrations directory, or asks to "add a field" or "add a column" to any Ghost model/table. Even if the user frames it as a feature or Linear issue, if the implementation requires a schema change, this skill applies.
+---
+
+# Create Database Migration
+
+## Instructions
+
+1. Create a new, empty migration file: `cd ghost/core && pnpm migrate:create <kebab-case-slug>`. IMPORTANT: do not create the migration file manually; always use this script to create the initial empty migration file. The slug must be kebab-case (e.g. `add-column-to-posts`).
+2. The above command will create a new directory in `ghost/core/core/server/data/migrations/versions` if needed, create the empty migration file with the appropriate name, and bump the core and admin package versions to RC if this is the first migration after a release.
+3. Update the migration file with the changes you want to make in the database, following the existing patterns in the codebase. Where appropriate, prefer to use the utility functions in `ghost/core/core/server/data/migrations/utils/*`.
+4. Update the schema definition file in `ghost/core/core/server/data/schema/schema.js`, and make sure it aligns with the latest changes from the migration.
+5. Test the migration manually: `cd ghost/core && pnpm knex-migrator migrate --v {version directory} --force`
+6. If adding or dropping a table, update `ghost/core/core/server/data/exporter/table-lists.js` as appropriate.
+7. If adding or dropping a table, also add or remove the table name from the expected tables list in `ghost/core/test/integration/exporter/exporter.test.js`. This test has a hardcoded alphabetically-sorted array of all database tables — it runs in CI integration tests (not unit tests) and will fail if the new table is missing.
+8. Run the schema integrity test, and update the hash: `cd ghost/core && pnpm test:single test/unit/server/data/schema/integrity.test.js`
+9. Run unit tests in Ghost core, and iterate until they pass: `cd ghost/core && pnpm test:unit`
+
+## Examples
+See [examples.md](examples.md) for example migrations.
+
+## Rules
+See [rules.md](rules.md) for rules that should always be followed when creating database migrations.

.agents/skills/create-database-migration/examples.md

@@ -0,0 +1,17 @@
+# Example database migrations
+
+## Create a table
+
+See [add mentions table](../../../ghost/core/core/server/data/migrations/versions/5.31/2023-01-19-07-46-add-mentions-table.js).
+
+## Add column(s) to an existing table
+
+See [add source columns to emails table](../../../ghost/core/core/server/data/migrations/versions/5.24/2022-11-21-09-32-add-source-columns-to-emails-table.js).
+
+## Add a setting
+
+See [add member track source setting](../../../ghost/core/core/server/data/migrations/versions/5.21/2022-10-27-09-50-add-member-track-source-setting.js)
+
+## Manipulate data
+
+See [update newsletter subscriptions](../../../ghost/core/core/server/data/migrations/versions/5.31/2022-12-05-09-56-update-newsletter-subscriptions.js).

.agents/skills/create-database-migration/rules.md

@@ -0,0 +1,33 @@
+# Rules for creating database migrations
+
+## Migrations must be idempotent
+
+It must be safe to run the migration twice. It's possible for a migration to stop executing due to external factors, so it must be safe to run the migration again successfully.
+
+## Migrations must NOT use the model layer
+
+Migrations are written for a specific version, and when they use the model layer, the asusmption is that they are using the models at that version. In reality, the models are of the version which is being migrated to, not from. This means that breaking changes in the models can inadvertently break migrations.
+
+## Migrations are Immutable
+
+Once migrations are on the `main` branch, they're final. If you need to make further changes after merging to main, create a new migration instead.
+
+## Use utility functions
+
+Wherever possible, use the utility functions in `ghost/core/core/server/data/migrations/utils`, such as `addTable`, `createTransactionalMigration`, and `addSetting`. These util functions have been tested and already include protections for idempotency, as well as log statements where appropriate to make migrations easier to debug.
+
+## Migration PRs should be as minimal as possible
+
+Migration PRs should contain the minimal amount of code to create the migration. Usually this means it should only include:
+- the new migration file
+- updates to the schema.js file
+- updated schema integrity hash tests
+- updated exporter table lists (when adding or removing tables)
+
+## Migrations should be defensive
+
+Protect against missing data. If a migration crashes, Ghost cannot boot.
+
+## Migrations should log every code path
+
+If we have to debug a migration, we need to know what it actually did. Without logging, that's impossible, so ensure all code paths and early returns contain logging. Note: when using the utility functions, logging is typically handled in the utility function itself, so no additional logging statements are necessary.