Doc update for gitops and SDL

mintlify/changelog/bytebase-1-8-0.mdx

@@ -11,7 +11,7 @@ import InstallUpgrade from '/snippets/install/install-upgrade.mdx';
 
 - Support syncing schema for MySQL.
 - Support approving issues via Lark (Feishu).
-- Support [SQL Review CI in the GitOps workflow](/gitops/sql-review-ci).
+- Support [SQL Review CI in the GitOps workflow](/gitops/migration-based-workflow/sql-review-ci).
 - DBAs and workspace admins can run SQL statements in Admin mode from the SQL Editor.
 - Support altering multiple databases on tenant mode.
 

mintlify/docs.json

@@ -130,9 +130,47 @@
             "pages": [
               "gitops/overview",
               "gitops/installation",
-              "gitops/develop",
-              "gitops/sql-review-ci",
-              "gitops/release"
+              {
+                "group": "Migration-Based Workflow",
+                "pages": [
+                  "gitops/migration-based-workflow/overview",
+                  "gitops/migration-based-workflow/develop",
+                  "gitops/migration-based-workflow/sql-review-ci",
+                  "gitops/migration-based-workflow/release",
+                  "gitops/migration-based-workflow/limitations"
+                ]
+              },
+              {
+                "group": "State-Based Workflow (SDL)",
+                "pages": [
+                  "gitops/state-based-workflow/overview",
+                  "gitops/state-based-workflow/develop",
+                  "gitops/state-based-workflow/sql-review-ci",
+                  "gitops/state-based-workflow/release",
+                  "gitops/state-based-workflow/limitations"
+                ]
+              },
+              {
+                "group": "Best Practices",
+                "pages": [
+                  "gitops/best-practices/overview",
+                  "gitops/best-practices/file-organization",
+                  "gitops/best-practices/migration-guidelines",
+                  "gitops/best-practices/git-and-cicd",
+                  "gitops/best-practices/sql-review-and-security",
+                  "gitops/best-practices/performance-and-drift"
+                ]
+              },
+              {
+                "group": "Troubleshooting",
+                "pages": [
+                  "gitops/troubleshooting/overview",
+                  "gitops/troubleshooting/release-and-plan",
+                  "gitops/troubleshooting/rollout",
+                  "gitops/troubleshooting/sdl-issues",
+                  "gitops/troubleshooting/cicd-issues"
+                ]
+              }
             ]
           },
           {

mintlify/gitops/best-practices/file-organization.mdx

@@ -0,0 +1,185 @@
+---
+title: File Organization
+---
+
+Proper file organization is crucial for maintainable GitOps workflows. This guide covers repository structures and directory layouts that scale with your team.
+
+## Repository Structure
+
+### Monorepo Approach
+
+Database migrations alongside application code:
+
+```
+my-app/
+├── src/                         # Application code
+├── migrations/                  # Database migrations
+│   ├── versioned/
+│   │   ├── 001__init.sql
+│   │   └── 002__add_users.sql
+│   └── schema/
+│       └── public.sql           # SDL if using declarative
+├── .github/workflows/
+│   └── bytebase-gitops.yml      # CI/CD integration
+└── README.md
+```
+
+**Benefits:**
+- Migrations versioned with application code
+- Atomic commits for schema + code changes
+- Single source of truth
+
+**Best for:**
+- Small to medium teams
+- Tight schema-code coupling
+- Monolithic or modular monolith architectures
+
+### Separate Repository
+
+Dedicated database repository:
+
+```
+database-schemas/
+├── app-db/
+│   ├── migrations/
+│   └── schema/
+├── analytics-db/
+│   └── migrations/
+└── .gitlab-ci.yml
+```
+
+**Benefits:**
+- Separation of concerns
+- Independent deployment cycles
+- Multiple teams/databases
+
+**Best for:**
+- Larger organizations
+- Dedicated database teams
+- Microservices with shared databases
+
+<Tip>
+  Choose based on your team structure. Co-located migrations work well for small teams with tight schema-code coupling. Separate repos fit larger organizations with dedicated database teams.
+</Tip>
+
+## Directory Layout
+
+### For Migration-Based Workflow
+
+**Option 1: Organized by Category**
+
+```
+migrations/
+├── baseline/
+│   └── 000__initial_schema.sql      # Initial baseline
+├── features/
+│   ├── 001__users.sql
+│   ├── 002__products.sql
+│   └── 003__orders.sql
+└── hotfixes/
+    └── 004__fix_index.sql
+```
+
+**Benefits:**
+- Clear organization by purpose
+- Easy to navigate
+- Separates routine changes from emergencies
+
+**Option 2: Flat Structure**
+
+```
+migrations/
+├── 001__initial_schema.sql
+├── 002__add_users.sql
+├── 003__add_products_dml.sql
+└── 004__add_indexes.sql
+```
+
+**Benefits:**
+- Simple and straightforward
+- Chronological ordering
+- Easy to understand
+
+### For State-Based Workflow (SDL)
+
+**Option 1: Organized by Schema**
+
+```
+schema/
+├── public.sql                # Main schema
+├── analytics.sql             # Analytics schema
+└── internal.sql              # Internal schema
+```
+
+**Benefits:**
+- Clear schema separation
+- Matches database structure
+- Easy to find objects
+
+**Option 2: Split by Object Type**
+
+```
+schema/
+├── 01_tables.sql
+├── 02_indexes.sql
+├── 03_views.sql
+├── 04_functions.sql
+└── 05_sequences.sql
+```
+
+**Benefits:**
+- Organized by DDL type
+- Predictable file structure
+- Clear dependencies (tables before indexes)
+
+### Hybrid Approach
+
+Combine both workflows for different purposes:
+
+```
+database/
+├── schema/               # SDL for structure (DDL)
+│   ├── public.sql
+│   └── analytics.sql
+├── migrations/           # Migrations for data (DML)
+│   ├── 001__seed_roles_dml.sql
+│   └── 002__migrate_users_dml.sql
+└── .github/workflows/
+    ├── schema-cicd.yml   # SDL pipeline
+    └── data-cicd.yml     # Migration pipeline
+```
+
+**Best for:**
+- Teams wanting declarative schema management
+- Projects requiring data migrations
+- Gradual migration from versioned to SDL
+
+## Documentation Structure
+
+Maintain supporting documentation alongside migrations:
+
+```
+database/
+├── migrations/
+├── schema/
+├── docs/
+│   ├── CHANGELOG.md          # Schema changelog
+│   ├── DEPENDENCIES.md       # Schema-app dependencies
+│   └── ROLLBACK_PLAN.md      # Rollback procedures
+└── test-data/
+    └── seed.sql              # Test data for development
+```
+
+---
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Migration Guidelines" icon="file-code" href="/gitops/best-practices/migration-guidelines">
+    Learn version numbering and file best practices
+  </Card>
+
+  <Card title="Git and CI/CD" icon="git-branch" href="/gitops/best-practices/git-and-cicd">
+    Set up branching strategies and pipelines
+  </Card>
+</CardGroup>