docs: update migration naming conventions to match implementation (#953)

- Change separator from double underscore (__) to single underscore (_)
- Add version pattern specification: ^[vV]?(\d+(\.\d+)*)
- Replace suffix-based migration type with comment-based approach
- Add MySQL-specific migration type section using -- migration-type: ghost
- Remove File Organization and Best Practices sections
- Simplify documentation for better readability

All changes align with the actual implementation in bytebase/action.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[email protected]>

Author: d-bytebase

mintlify/gitops/migration-based-workflow/develop.mdx

@@ -9,16 +9,17 @@ Create SQL migration files following naming conventions that enable proper versi
 Migration filenames must follow this structure:
 
 ```
-<Version>__<Description>_<Suffix>.sql
+<Version>_<Description>.sql
 ```
 
 **Components:**
 
-1. **Version** (required) - Must begin with a number, optional `v` or `V` prefix
-2. **Double underscore** (`__`) separator
+1. **Version** (required) - Optional `v` or `V` prefix, followed by one or more numbers separated by dots
+   - Pattern: `^[vV]?(\d+(\.\d+)*)`
+   - Examples: `v1.2.3`, `1.0`, `V2`
+2. **Underscore** (`_`) separator
 3. **Description** - Human-readable description using underscores or hyphens
-4. **Suffix** (optional) - Migration type indicator
-5. **`.sql`** file extension
+4. **`.sql`** file extension
 
 ## Version Formats
 
@@ -29,8 +30,8 @@ Choose a versioning strategy that fits your team:
     **Timestamp-Based** - Recommended for teams with parallel development
 
     ```
-    20250120143000__add_user_email.sql
-    20250121091500__create_orders_table.sql
+    20250120143000_add_user_email.sql
+    20250121091500_create_orders_table.sql
     ```
 
     Format: `YYYYMMDDHHmmss`
@@ -46,10 +47,10 @@ Choose a versioning strategy that fits your team:
     **Semantic Versioning** - Meaningful version numbers
 
     ```
-    v1.0.0__initial_release.sql
-    v1.1.0__add_user_profiles.sql
-    v1.1.1__fix_profile_constraint.sql
-    v2.0.0__redesign_authentication.sql
+    v1.0.0_initial_release.sql
+    v1.1.0_add_user_profiles.sql
+    v1.1.1_fix_profile_constraint.sql
+    v2.0.0_redesign_authentication.sql
     ```
 
     ✅ Conveys change significance
@@ -63,9 +64,9 @@ Choose a versioning strategy that fits your team:
     **Simple Sequential** - Easy to understand
 
     ```
-    001__initial_schema.sql
-    002__add_users.sql
-    003__add_products.sql
+    001_initial_schema.sql
+    002_add_users.sql
+    003_add_products.sql
     ```
 
     ✅ Simple and clear
@@ -75,104 +76,21 @@ Choose a versioning strategy that fits your team:
   </Tab>
 </Tabs>
 
-## Change Type Suffixes
+## Migration Type (MySQL Only)
 
-Specify the migration type using an optional suffix:
-
-| Suffix | Type | Description | Use Cases |
-|--------|------|-------------|-----------|
-| *(none)* | **DDL** | Data Definition Language | CREATE, ALTER, DROP tables, indexes, constraints |
-| `_dml` | **DML** | Data Manipulation Language | INSERT, UPDATE, DELETE, data migrations |
-| `_ghost` | **Ghost** | gh-ost online migration | Zero-downtime MySQL schema changes |
-
-**Examples:**
-
-```
-v1.0.0__create_schema.sql           (DDL - default)
-v1.1.0__seed_initial_data_dml.sql   (DML - data changes)
-v1.2.0__add_user_index_ghost.sql    (Ghost - online schema change)
-```
-
-<Card title="Online Schema Migration" icon="bolt" href="/change-database/online-schema-migration-for-mysql">
-  Learn about gh-ost for zero-downtime MySQL migrations
-</Card>
-
-## File Organization
-
-**Recommended structure:**
-
-```
-migrations/
-├── 001__initial_schema.sql
-├── 002__add_users.sql
-├── 003__add_products_dml.sql
-└── 004__add_indexes.sql
-```
-
-**Or with subdirectories:**
-
-```
-migrations/
-├── baseline/
-│   └── 000__initial_schema.sql
-├── features/
-│   ├── 001__users.sql
-│   ├── 002__products.sql
-│   └── 003__orders.sql
-└── hotfixes/
-    └── 004__fix_index.sql
-```
-
-## Best Practices
-
-**Keep migrations small and focused:**
-
-```sql
-✅ Good - Single, clear purpose
--- 005__add_user_email.sql
-ALTER TABLE users ADD COLUMN email TEXT;
-```
+For zero-downtime MySQL schema changes, add this comment at the top of your file:
 
 ```sql
-❌ Bad - Too large and unfocused
--- 005__big_refactor.sql
-ALTER TABLE users ADD COLUMN email TEXT;
-ALTER TABLE users ADD COLUMN phone TEXT;
-CREATE TABLE user_preferences (...);
--- 500 more lines
-```
-
-**Add comments for complex logic:**
+-- migration-type: ghost
 
-```sql
--- 020__migrate_legacy_permissions_dml.sql
--- Migrates old role system to new permission model
--- Old: roles.name -> New: permissions.scope + permissions.action
-
-UPDATE permissions
-SET scope = CASE
-    WHEN roles.name = 'admin' THEN 'database'
-    WHEN roles.name = 'editor' THEN 'database'
-END
-FROM roles
-WHERE permissions.role_id = roles.id;
+ALTER TABLE users ADD COLUMN email VARCHAR(255);
 ```
 
-**Use transactions when possible:**
-
-```sql
--- 015__multi_step_migration_dml.sql
-BEGIN;
-
-UPDATE users SET status = 'migrated' WHERE status = 'legacy';
+This uses [gh-ost](https://github.com/github/gh-ost) to apply changes without blocking your database.
 
-INSERT INTO user_audit_log (user_id, action)
-SELECT id, 'status_migrated'
-FROM users
-WHERE status = 'migrated';
-
-COMMIT;
-```
+<Card title="Online Schema Migration" icon="bolt" href="/change-database/online-schema-migration-for-mysql">
+  Learn more about gh-ost
+</Card>
 
 ---