docs: order clarification

Author: dieppa

docs/changes/anatomy-and-structure.md

@@ -38,6 +38,22 @@ The `order` determines when the Change executes relative to others.
 - Minimum 4 digits recommended for future expansion
 - Determines execution order across all target systems
 - Cannot be changed once deployed
+
+:::warning Order Field Rules
+- The `order` must be specified in **at least one** of these places:
+  - In the file/class name following the pattern `_ORDER_DescriptiveName.[java|yaml]`
+  - In the annotation (@Change) or YAML structure
+- Both are optional, but **at least one is required**
+- If order is specified in **both** locations, they **must be identical**
+- For file/class names:
+  - Must start with underscore `_`
+  - Order is extracted between the first `_` and the last `_`
+  - Allows intermediate underscores (e.g., `_2025_09_01_09_00_0001_CreateUserTable.java`)
+  - Order extracted: everything between first and last underscore (e.g., `2025_09_01_09_00_0001`)
+- Orders are evaluated in alphanumeric order
+:::
+
+For recommendations on order field placement and naming patterns, see [Best Practices - Naming Patterns](./best-practices#follow-consistent-naming-patterns).
 ____
 ### `author` - Responsibility tracking
 Identifies who is responsible for this change.

docs/changes/best-practices.md

@@ -239,18 +239,36 @@ public void removeEmailIndexAndRevertSchema(MongoDatabase db) { }
 ### Follow consistent naming patterns
 
 **File names:**
-- Use `_XXXX_DescriptiveName` format
-- Match the order in `@Change` annotation
+- Use `_ORDER_DescriptiveName` format where ORDER is extracted between first and last underscores
+- When using this naming pattern, the order in `@Change` annotation or YAML is optional
 - Use PascalCase for class names
+- Pattern supports flexible ordering: timestamps, hierarchical numbering, etc.
 
 **Good examples:**
 ```
 _0001_CreateUserIndexes.java
 _0002_MigrateUserData.java
 _0003_AddUserPreferences.java
 _0100_OptimizeUserQueries.java
+_2025_09_01_MigrateToNewFormat.java
+_2025_09_01_09_00_0001_ComplexMigration.yaml
 ```
 
+:::tip Recommendation
+We recommend specifying the order in the file/class name rather than in the annotation/yaml:
+- Makes execution order immediately visible when browsing folders
+- Easier to identify and list changes in their location
+- Reduces redundancy and potential mismatches
+- Supports flexible ordering schemes (timestamps, hierarchical numbering, etc.)
+
+Examples:
+- `_0001_CreateUserTable.java` → order: "0001" (no need for order in @Change)
+- `_2025_09_01_MigrateData.yaml` → order: "2025_09_01" (no need for order in YAML)
+- `_2025_09_01_09_00_0001_ComplexChange.java` → order: "2025_09_01_09_00_0001"
+:::
+
+
+For detailed rules about order field placement (filename vs annotation), see [Anatomy & Structure - Order](./anatomy-and-structure#order---execution-sequence).
 
 ---
 

docs/changes/types-and-implementation.md

@@ -56,9 +56,9 @@ Code-based Changes are written in Java, Kotlin, or Groovy with annotations. They
 
 ```java
 @TargetSystem("user-database")
-@Change(id = "migrate-user-emails", order = "0001", author = "data-team")
+@Change(id = "migrate-user-emails", author = "data-team")  // order extracted from filename
 public class _0001_MigrateUserEmails {
-    
+
     @Apply
     public void apply(MongoDatabase database, ClientSession session) {
         // Custom implementation logic with full programmatic control
@@ -67,7 +67,7 @@ public class _0001_MigrateUserEmails {
             new Document("email", new Document("$exists", true)),
             new Document("$set", new Document("emailVerified", false)));
     }
-    
+
     @Rollback
     public void rollback(MongoDatabase database, ClientSession session) {
         // Rollback logic
@@ -102,7 +102,12 @@ src/main/java/com/yourapp/changes/
 
 ### Best practices:
 - **Keep together**: Store both code and template files in the same directory
-- **Consistent naming**: Follow `_XXXX_DescriptiveName` pattern for both types
+- **Consistent naming**: Follow `_ORDER_DescriptiveName` pattern for both types
+- **Order in filename**: When using the naming pattern, order in annotation/yaml is optional
+
+:::info Order Field Rules
+When using the `_ORDER_DescriptiveName` pattern, the order field in annotations or YAML becomes optional. For complete rules about order field placement, see [Anatomy & Structure - Order](./anatomy-and-structure#order---execution-sequence).
+:::
 
 ## Template development
 

docs/flamingock-library-config/setup-and-stages.md

@@ -273,20 +273,28 @@ To ensure clarity and enforce ordering, we recommend naming changes using the fo
 ```
 _0001_CREATE_CLIENTS_TABLE.java
 _0002_ADD_INDEX_TO_EMAIL.yaml
+_2025_09_01_MIGRATE_DATA.java
+_2025_09_01_09_00_0001_COMPLEX_CHANGE.yaml
 ```
 
-- `XXXX`: The execution order of the change
+- `ORDER`: The execution order extracted between the first `_` and last `_` (supports timestamps, hierarchical numbering)
 - `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
+- Makes execution order immediately visible when browsing folders
 - Works across both code-based and template-based formats
-- Makes the execution order obvious at a glance
+- Supports flexible ordering schemes (simple numbers, dates, timestamps)
 - Ensures consistent naming and project hygiene
 
 :::tip
 While Java typically avoids underscores and leading digits, change units are not traditional classes. Prioritizing **readability and order** is more valuable in this context.
 :::
 
+:::info Complete Order Field Rules
+For detailed rules about order field placement and how filename order works with annotations, see [Change Anatomy - Order](../changes/anatomy-and-structure#order---execution-sequence).
+:::
+
 
 
 ## 🛠 Troubleshooting