lmiranda
2d51df7a42
Phase 1b: Rename all ~94 commands across 12 plugins to /<noun> <action> sub-command pattern. Git-flow consolidated from 8→5 commands (commit variants absorbed into --push/--merge/--sync flags). Dispatch files, name: frontmatter, and cross-reference updates for all plugins. Phase 2: Design documents for 8 new plugins in docs/designs/. Phase 3: Scaffold 8 new plugins — saas-api-platform, saas-db-migrate, saas-react-platform, saas-test-pilot, data-seed, ops-release-manager, ops-deploy-pipeline, debug-mcp. Each with plugin.json, commands, agents, skills, README, and claude-md-integration. Marketplace grows from 12→20. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
105 lines
3.3 KiB
Markdown
105 lines
3.3 KiB
Markdown
---
|
|
name: naming-conventions
|
|
description: Migration file naming rules — timestamp prefixes, descriptive suffixes, ordering
|
|
---
|
|
|
|
# Naming Conventions
|
|
|
|
## Purpose
|
|
|
|
Defines standard naming patterns for migration files across all supported tools. This skill ensures consistent, descriptive, and correctly ordered migration files.
|
|
|
|
---
|
|
|
|
## General Rules
|
|
|
|
1. **Use lowercase with underscores** for descriptions (snake_case)
|
|
2. **Be descriptive but concise**: Describe WHAT changes, not WHY
|
|
3. **Use verb prefixes**: `add_`, `drop_`, `rename_`, `alter_`, `create_`, `remove_`
|
|
4. **Include the table name** when the migration affects a single table
|
|
5. **Never use generic names** like `migration_1`, `update`, `fix`
|
|
|
|
---
|
|
|
|
## Tool-Specific Patterns
|
|
|
|
### Alembic
|
|
|
|
**Format:** `{revision_hash}_{description}.py`
|
|
|
|
The revision hash is auto-generated by Alembic. The description is provided by the user.
|
|
|
|
| Example | Description |
|
|
|---------|-------------|
|
|
| `a1b2c3d4_create_users_table.py` | Initial table creation |
|
|
| `e5f6g7h8_add_email_to_users.py` | Add column |
|
|
| `i9j0k1l2_drop_legacy_users_columns.py` | Remove columns |
|
|
| `m3n4o5p6_rename_orders_total_to_amount.py` | Rename column |
|
|
| `q7r8s9t0_add_index_on_orders_user_id.py` | Add index |
|
|
|
|
**Description rules for Alembic:**
|
|
- Max 60 characters for the description portion
|
|
- No spaces (use underscores)
|
|
- Alembic auto-generates the revision hash
|
|
|
|
### Prisma
|
|
|
|
**Format:** `{YYYYMMDDHHMMSS}_{description}/migration.sql`
|
|
|
|
| Example | Description |
|
|
|---------|-------------|
|
|
| `20240115120000_create_users_table/migration.sql` | Initial table |
|
|
| `20240120093000_add_email_to_users/migration.sql` | Add column |
|
|
| `20240201110000_add_orders_table/migration.sql` | New table |
|
|
|
|
**Description rules for Prisma:**
|
|
- Prisma generates the timestamp automatically with `prisma migrate dev`
|
|
- Description is the `--name` argument
|
|
- Use snake_case, no spaces
|
|
|
|
### Raw SQL
|
|
|
|
**Format:** `{NNN}_{description}.sql`
|
|
|
|
Sequential numbering with zero-padded prefix:
|
|
|
|
| Example | Description |
|
|
|---------|-------------|
|
|
| `001_create_users_table.sql` | First migration |
|
|
| `002_add_email_to_users.sql` | Second migration |
|
|
| `003_create_orders_table.sql` | Third migration |
|
|
|
|
**Numbering rules:**
|
|
- Zero-pad to 3 digits minimum (001, 002, ..., 999)
|
|
- If project exceeds 999, use 4 digits (0001, 0002, ...)
|
|
- Never reuse numbers, even for deleted migrations
|
|
- Gaps in sequence are acceptable (001, 002, 005 is fine)
|
|
|
|
---
|
|
|
|
## Description Verb Prefixes
|
|
|
|
| Prefix | Use When |
|
|
|--------|----------|
|
|
| `create_` | New table |
|
|
| `add_` | New column, index, or constraint to existing table |
|
|
| `drop_` | Remove table |
|
|
| `remove_` | Remove column, index, or constraint |
|
|
| `rename_` | Rename table or column |
|
|
| `alter_` | Change column type or constraint |
|
|
| `backfill_` | Data-only migration (populate column values) |
|
|
| `merge_` | Combine tables or columns |
|
|
| `split_` | Separate table or column into multiple |
|
|
|
|
---
|
|
|
|
## Anti-Patterns
|
|
|
|
| Bad Name | Problem | Better Name |
|
|
|----------|---------|-------------|
|
|
| `migration_1.py` | Not descriptive | `create_users_table.py` |
|
|
| `update.sql` | Too vague | `add_status_to_orders.sql` |
|
|
| `fix_bug.py` | Describes why, not what | `alter_email_column_length.py` |
|
|
| `changes.sql` | Not descriptive | `add_index_on_users_email.sql` |
|
|
| `final_migration.py` | Nothing is ever final | `remove_deprecated_columns.py` |
|