docs: fixed order (2nd phase)

Author: dieppa

.claude/settings.local.json

@@ -17,7 +17,19 @@
       "Bash(yarn build)",
       "Read(//Users/dieppa/workspace/flamingock/**)",
       "Bash(./gradlew:*)",
-      "Bash(sort:*)"
+      "Bash(sort:*)",
+      "Bash(docs/overview/Change-as-Code.md)",
+      "Bash({} ;)",
+      "Bash(docs/flamingock-library-config/setup-and-stages.md)",
+      "Bash(docs/changes/domain-coupling.md)",
+      "Bash(docs/changes/introduction.md)",
+      "Bash(docs/target-systems/sql-target-system.md)",
+      "Bash(docs/changes/types-and-implementation.md)",
+      "Bash(docs/target-systems/mongodb-springdata-target-system.md)",
+      "Bash(docs/changes/best-practices.md)",
+      "Bash(docs/target-systems/dynamodb-target-system.md)",
+      "Bash(docs/target-systems/couchbase-target-system.md)",
+      "Bash(docs/target-systems/mongodb-target-system.md)"
     ],
     "deny": []
   }

FLAMINGOCK_RECOVERY_SAFETY_KNOWLEDGE.md

@@ -17,7 +17,7 @@ Once a Change is deployed, never modify it. Create new Changes for corrections.
 ```java
 // Modifying an existing Change after deployment
 @Change(id = "add-user-field", author = "team")  // order extracted from filename
-public class _20250923_01_AddUserField {
+public class _0001__AddUserField {
     @Apply
     public void apply(MongoDatabase db) {
         // Original: db.getCollection("users").updateMany(/* add field */)
@@ -30,7 +30,7 @@ public class _20250923_01_AddUserField {
 ```java
 // Keep the original unchanged
 @Change(id = "add-user-field", author = "team")  // order extracted from filename
-public class _20250923_01_AddUserField {
+public class _0001__AddUserField {
     @Apply
     public void apply(MongoDatabase db) {
         // Original logic remains unchanged
@@ -39,7 +39,7 @@ public class _20250923_01_AddUserField {
 
 // Create a new Change for corrections
 @Change(id = "fix-user-field-values", author = "team")  // order extracted from filename
-public class _20250923_02_FixUserFieldValues {
+public class _0002__FixUserFieldValues {
     @Apply
     public void apply(MongoDatabase db) {
         // Correction logic
@@ -83,7 +83,7 @@ Every Change must have a `@Rollback` method, regardless of target system type.
 **Example with comprehensive rollback:**
 ```java
 @Change(id = "setup-user-indexes", author = "db-team")  // order extracted from filename
-public class _20250923_01_SetupUserIndexes {
+public class _0001__SetupUserIndexes {
 
     @Apply
     public void apply(MongoDatabase database) {
@@ -127,7 +127,7 @@ Each Change should address one logical change. Avoid combining unrelated operati
 **❌ Avoid mixing concerns:**
 ```java
 @Change(id = "big-refactor", author = "team")  // order extracted from filename
-public class _20250923_01_BigRefactor {
+public class _0001__BigRefactor {
     @Apply
     public void apply(MongoDatabase db, KafkaProducer producer) {
         // Adding user field
@@ -146,13 +146,13 @@ public class _20250923_01_BigRefactor {
 ```java
 @TargetSystem("user-database")
 @Change(id = "add-user-status", author = "team")  // order extracted from filename
-public class _20250923_01_AddUserStatus {
+public class _0001__AddUserStatus {
     // Focus: User schema change only
 }
 
 @TargetSystem("kafka-events")
 @Change(id = "create-user-topic", author = "team")  // order extracted from filename
-public class _20250923_01_CreateUserTopic {
+public class _0001__CreateUserTopic {
     // Focus: Kafka topic creation only
 }
 ```
@@ -166,7 +166,7 @@ Make operations safe to re-run whenever possible.
 **Example: Idempotent field addition:**
 ```java
 @Change(id = "add-user-preferences", author = "team")  // order extracted from filename
-public class _20250923_01_AddUserPreferences {
+public class _0001__AddUserPreferences {
 
     @Apply
     public void apply(MongoDatabase database) {
@@ -240,35 +240,33 @@ public void removeEmailIndexAndRevertSchema(MongoDatabase db) { }
 
 **File names:**
 - Use `_ORDER_DescriptiveName` format where ORDER is extracted between first and last underscores
-- **Recommended format**: `YYYYMMDD_NN` where:
-  - YYYY = year, MM = month, DD = day
-  - NN = sequence number (01-99) for changes on the same day
+- **Recommended format for order**: `NNNN` with left-padding zeros (e.g., `0001`, `0002`, `0010`)
 - When using this naming pattern, the order in `@Change` annotation or YAML is optional
 - Use PascalCase for class names
 
 **Good examples:**
 ```
-_20250923_01_CreateUserIndexes.java
-_20250923_02_MigrateUserData.java
-_20250924_01_AddUserPreferences.java
-_20250925_01_OptimizeUserQueries.java
-_20250930_01_MigrateToNewFormat.yaml
+_0001__CreateUserIndexes.java
+_0002__MigrateUserData.java
+_0002__AddUserPreferences.java
+_0005__OptimizeUserQueries.java
+_0004__MigrateToNewFormat.yaml
 ```
 
 :::tip Recommendation
-We recommend specifying the order in the file/class name using the `YYYYMMDD_NN` format:
+We recommend specifying the order in the file/class name using the `NN` format:
 
 **Benefits:**
-- **Natural chronological sorting** - Files automatically sort by date in folders
-- **Clear timeline visibility** - Instantly see when changes were created
-- **Practical daily limit** - 99 changes per day is more than sufficient
-- **Easy identification** - Quick visual scan shows change history
+- **Simple and clear** - Easy to understand and implement
+- **Natural sorting** - Files automatically sort numerically
+- **No complexity** - Just sequential numbering
+- **Easy identification** - Quick visual scan shows execution order
 - **No annotation needed** - Order is extracted from filename
 
 Examples:
-- `_20250923_01_CreateUserTable.java` → order: "20250923_01" (no need for order in @Change)
-- `_20250923_02_MigrateData.yaml` → order: "20250923_02" (no need for order in YAML)
-- `_20250924_01_AddIndexes.java` → order: "20250924_01"
+- `_0001__CreateUserTable.java` → order: "0001" (no need for order in @Change)
+- `_0002__MigrateData.yaml` → order: "0002" (no need for order in YAML)
+- `_0004__AddIndexes.java` → order: "0004"
 :::
 
 
@@ -298,11 +296,11 @@ Changes should be organized chronologically by their order within stages. If you
 
 ```
 src/main/java/com/company/changes/
-├── _20250923_01_CreateUserCollection.java
-├── _20250923_02_AddUserIndexes.java
-├── _20250924_01_MigrateUserData.java
-├── _20250924_02_CreateOrdersTable.java
-└── _20250925_01_AddOrderStatusColumn.java
+├── _0001__CreateUserCollection.java
+├── _0002__AddUserIndexes.java
+├── _0003__MigrateUserData.java
+├── _0004__CreateOrdersTable.java
+└── _0005__AddOrderStatusColumn.java
 ```
 
 ## Testing and validation
@@ -318,7 +316,7 @@ public void testUserMigrationChange() {
     MongoDatabase testDb = getTestDatabase();
     insertTestUsers(testDb);
 
-    var change = new _20250923_01_MigrateUsers();
+    var change = new _0001__MigrateUsers();
 
     // Act - Test execution
     change.execute(testDb);

docs/changes/best-practices.md

@@ -38,7 +38,7 @@ You create a Change that uses this domain class:
 
 ```java
 @Change(id = "add-premium-customers", order = "20250923_01", author = "team")
-public class _20250923_01_AddPremiumCustomers {
+public class _0001__AddPremiumCustomers {
 
     @Apply
     public void apply(CustomerRepository repository) {
@@ -55,7 +55,7 @@ public class _20250923_01_AddPremiumCustomers {
 Six months later, your team decides `middleName` is unnecessary and removes it from the `Customer` class. Now:
 
 - ✅ Your application works fine with the updated model
-- ❌ The Change `_20250923_01_AddPremiumCustomers` no longer compiles
+- ❌ The Change `_0001__AddPremiumCustomers` no longer compiles
 - ❌ You can't run Flamingock in new environments
 - ❌ CI/CD pipelines break
 
@@ -69,7 +69,7 @@ Here's how the same Change looks using generic structures:
 
 ```java
 @Change(id = "add-premium-customers", order = "20250923_01", author = "team")
-public class _20250923_01_AddPremiumCustomers {
+public class _0001__AddPremiumCustomers {
 
     @Apply
     public void apply(RestTemplate restTemplate) {

docs/changes/domain-coupling.md

@@ -39,7 +39,7 @@ Written in Java, Kotlin, or Groovy with annotations. Best for complex logic or w
 ```java
 @TargetSystem("user-database")
 @Change(id = "add-user-status", author = "dev-team")
-public class _20250923_01_AddUserStatus {
+public class _0001__AddUserStatus {
 
     @Apply
     public void apply(MongoDatabase database) {
@@ -58,9 +58,8 @@ public class _20250923_01_AddUserStatus {
 Use YAML or JSON definitions with reusable templates. Perfect for repetitive operations and standardized patterns.
 
 ```yaml
-# File: _20250923_02_add_status_column.yaml
+# File: _0002__AddStatusColumn.yaml
 id: add_status_column
-order: "20250923_02"
 author: "db-team"
 templateName: sql-template
 apply: "ALTER TABLE orders ADD COLUMN status VARCHAR(20);"

docs/changes/introduction.md

@@ -25,9 +25,8 @@ Template-based Changes use YAML or JSON files with reusable templates. Templates
 ### Basic YAML structure
 
 ```yaml
-# File: _20250923_01_add_user_index.yaml
+# File: _0001__AddUserIndex.yaml
 id: add_user_index
-order: "20250923_01"
 author: "database-team"
 description: "Add index on user email field for faster lookups"
 targetSystem: "user-database"
@@ -57,7 +56,7 @@ Code-based Changes are written in Java, Kotlin, or Groovy with annotations. They
 ```java
 @TargetSystem("user-database")
 @Change(id = "migrate-user-emails", author = "data-team")  // order extracted from filename
-public class _20250923_01_MigrateUserEmails {
+public class _0001__MigrateUserEmails {
 
     @Apply
     public void apply(MongoDatabase database, ClientSession session) {
@@ -93,16 +92,16 @@ public class _20250923_01_MigrateUserEmails {
 ### Recommended project structure:
 ```
 src/main/java/com/yourapp/changes/
-├── _20250923_01_CreateUserIndexes.java
-├── _20250923_02_AddUserStatus.yaml
-├── _20250924_01_MigrateUserData.java
-├── _20250924_02_SetupNotifications.yaml
-└── _20250925_01_OptimizeQueries.java
+├── _0001__CreateUserIndexes.java
+├── _0002__AddUserStatus.yaml
+├── _0003__MigrateUserData.java
+├── _0004__SetupNotifications.yaml
+└── _0003__OptimizeQueries.java
 ```
 
 ### Best practices:
 - **Keep together**: Store both code and template files in the same directory
-- **Consistent naming**: Follow `_ORDER_DescriptiveName` pattern for both types (recommended: `YYYYMMDD_NN`)
+- **Consistent naming**: Follow `_ORDER__CHANGE_NAME` pattern for both types (recommended: `NN`)
 - **Order in filename**: When using the naming pattern, order in annotation/yaml is optional
 
 :::info Order Field Rules

docs/changes/types-and-implementation.md

@@ -230,8 +230,8 @@ src/
         yourapp/
           flamingock/
             users/
-              _20250923_01_CreateUsersTable.java
-              _20250923_02_AaddIndex.yaml
+              _0001__CreateUsersTable.java
+              _0002__AddIndex.yaml
 ```
 
 
@@ -271,22 +271,22 @@ We strongly recommend placing all your changes — code-based and template-based
 To ensure clarity and enforce ordering, we recommend naming changes using the following format:
 
 ```
-_20250923_01_CreateClientsTable.java
-_20250923_02_AaddindexToEmail.yaml
-_20250924_01_MigrateData.java
-_20250925_01_ComplexChange.yaml
+_0001__CreateClientsTable.java
+_0002__AddIndexToEmail.yaml
+_0003__MigrateData.java
+_0004__ComplexChange.yaml
 ```
 
 - `ORDER`: The execution order extracted between the first `_` and last `_`
-  - **Recommended format**: `YYYYMMDD_NN` where YYYY=year, MM=month, DD=day, NN=sequence (01-99)
+  - **Recommended format**: `NNNN` with left-padding zeros (e.g., `0001`, `0002`, `0010`)
 - `CHANGE_NAME`: Descriptive name of what the change does
 
 This convention:
 - **Eliminates the need for order in annotations/YAML** - the order is extracted from the filename
-- **Natural chronological sorting** - files automatically sort by date in folders
-- **Clear timeline visibility** - instantly see when changes were created
+- **Natural sequential sorting** - files automatically sort numerically
+- **Clear execution order** - instantly see the sequence of changes
 - Works across both code-based and template-based formats
-- **Practical daily limit** - 99 changes per day is more than sufficient
+- **Sufficient capacity** - supports up to 99 changes with two-digit format
 - Ensures consistent naming and project hygiene
 
 :::tip