|
| 1 | +# Engine X Terminology Changes |
| 2 | + |
| 3 | +This document summarizes the comprehensive terminology changes made to rename "engine reorg" to "engine x" and update pre-allocation terminology throughout the codebase. |
| 4 | + |
| 5 | +## 🔄 Engine Reorg → Engine X Changes |
| 6 | + |
| 7 | +### Class & Type Renames |
| 8 | +```diff |
| 9 | +- BlockchainEngineReorgFixture |
| 10 | ++ BlockchainEngineXFixture |
| 11 | + |
| 12 | +- blockchain_test_engine_reorg |
| 13 | ++ blockchain_test_engine_x |
| 14 | + |
| 15 | +- blockchain_tests_engine_reorg |
| 16 | ++ blockchain_tests_engine_x |
| 17 | +``` |
| 18 | + |
| 19 | +### File Renames |
| 20 | +```diff |
| 21 | +- docs/running_tests/test_formats/blockchain_test_engine_reorg.md |
| 22 | ++ docs/running_tests/test_formats/blockchain_test_engine_x.md |
| 23 | +``` |
| 24 | + |
| 25 | +### Directory/Path Changes |
| 26 | +```diff |
| 27 | +- fixtures/blockchain_tests_engine_reorg/ |
| 28 | ++ fixtures/blockchain_tests_engine_x/ |
| 29 | + |
| 30 | +- --sim.limit="...blockchain_test_engine_reorg..." |
| 31 | ++ --sim.limit="...blockchain_test_engine_x..." |
| 32 | +``` |
| 33 | + |
| 34 | +## 🔄 Pre-Allocation Terminology Changes |
| 35 | + |
| 36 | +### Command-Line Flags |
| 37 | +```diff |
| 38 | +- --generate-shared-pre |
| 39 | ++ --generate-grouped-pre-allocs |
| 40 | + |
| 41 | +- --use-shared-pre |
| 42 | ++ --use-grouped-pre-allocs |
| 43 | +``` |
| 44 | + |
| 45 | +### Class Renames |
| 46 | +```diff |
| 47 | +- SharedPreStateGroup |
| 48 | ++ PreAllocGroup |
| 49 | + |
| 50 | +- SharedPreState |
| 51 | ++ PreAllocGroups |
| 52 | +``` |
| 53 | + |
| 54 | +### File Renames |
| 55 | +```diff |
| 56 | +- src/ethereum_test_fixtures/shared_alloc.py |
| 57 | ++ src/ethereum_test_fixtures/pre_alloc_groups.py |
| 58 | +``` |
| 59 | + |
| 60 | +### Method Renames |
| 61 | +```diff |
| 62 | +- update_shared_pre_state() |
| 63 | ++ update_pre_alloc_groups() |
| 64 | + |
| 65 | +- compute_shared_pre_alloc_hash() |
| 66 | ++ compute_pre_alloc_group_hash() |
| 67 | + |
| 68 | +- shared_pre_alloc_folder_path |
| 69 | ++ grouped_pre_allocs_folder_path |
| 70 | +``` |
| 71 | + |
| 72 | +### Variable Name Changes |
| 73 | +```diff |
| 74 | +- shared_pre_state |
| 75 | ++ grouped_pre_allocs |
| 76 | + |
| 77 | +- shared_alloc |
| 78 | ++ pre_alloc_group |
| 79 | + |
| 80 | +- pre_state |
| 81 | ++ pre_alloc_groups |
| 82 | +``` |
| 83 | + |
| 84 | +### Import Statement Updates |
| 85 | +```diff |
| 86 | +- from ethereum_test_fixtures import SharedPreState, SharedPreStateGroup |
| 87 | ++ from ethereum_test_fixtures import PreAllocGroups, PreAllocGroup |
| 88 | + |
| 89 | +- from ethereum_test_fixtures.shared_alloc import SharedPreStateGroup |
| 90 | ++ from ethereum_test_fixtures.pre_alloc_groups import PreAllocGroup |
| 91 | +``` |
| 92 | + |
| 93 | +### Configuration Option References |
| 94 | +```diff |
| 95 | +- config.getoption("generate_shared_pre") |
| 96 | ++ config.getoption("generate_grouped_pre_allocs") |
| 97 | + |
| 98 | +- config.getoption("use_shared_pre") |
| 99 | ++ config.getoption("use_grouped_pre_allocs") |
| 100 | +``` |
| 101 | + |
| 102 | +## 📝 Terminology Philosophy |
| 103 | + |
| 104 | +### Engine X |
| 105 | +- **Purpose**: Generic naming that doesn't imply a specific technical approach |
| 106 | +- **Before**: "engine reorg" suggested blockchain reorganization as the primary mechanism |
| 107 | +- **After**: "engine x" is implementation-neutral and future-proof |
| 108 | + |
| 109 | +### Pre-Allocation Groups |
| 110 | +- **Purpose**: Emphasize grouping/organization over sharing |
| 111 | +- **Before**: "shared pre-allocation" focused on the sharing aspect |
| 112 | +- **After**: "pre-allocation groups" emphasizes that tests are organized into groups based on their pre-allocation requirements |
| 113 | + |
| 114 | +## 🛠️ Rebasing Guidelines |
| 115 | + |
| 116 | +### For Code Changes |
| 117 | +1. **Search and replace** the class/method names listed above |
| 118 | +2. **Update import statements** to use new module and class names |
| 119 | +3. **Check command-line usage** for flag name changes |
| 120 | +4. **Update variable names** that reference the old terminology |
| 121 | +5. **Review error messages** and docstrings for terminology updates |
| 122 | + |
| 123 | +### For Documentation |
| 124 | +1. **Replace references** to "engine reorg" with "engine x" |
| 125 | +2. **Update flag documentation** to use new flag names |
| 126 | +3. **Change "shared pre-allocation"** to "pre-allocation groups" |
| 127 | +4. **Update file paths** in examples and references |
| 128 | + |
| 129 | +### For Tests |
| 130 | +1. **Update test method calls** to use new method names |
| 131 | +2. **Check fixture imports** for renamed classes |
| 132 | +3. **Update command-line test invocations** with new flags |
| 133 | +4. **Verify test data paths** for directory name changes |
| 134 | + |
| 135 | +### Common Patterns to Update |
| 136 | + |
| 137 | +#### Config Option Checks |
| 138 | +```diff |
| 139 | +- if config.getoption("generate_shared_pre"): |
| 140 | ++ if config.getoption("generate_grouped_pre_allocs"): |
| 141 | + |
| 142 | +- if config.getoption("use_shared_pre"): |
| 143 | ++ if config.getoption("use_grouped_pre_allocs"): |
| 144 | +``` |
| 145 | + |
| 146 | +#### Type Annotations |
| 147 | +```diff |
| 148 | +- def process(groups: SharedPreState) -> None: |
| 149 | ++ def process(groups: PreAllocGroups) -> None: |
| 150 | + |
| 151 | +- def create_group() -> SharedPreStateGroup: |
| 152 | ++ def create_group() -> PreAllocGroup: |
| 153 | +``` |
| 154 | + |
| 155 | +#### Error Messages |
| 156 | +```diff |
| 157 | +- "shared pre-allocation state not found" |
| 158 | ++ "pre-allocation groups not found" |
| 159 | + |
| 160 | +- "run with --generate-shared-pre first" |
| 161 | ++ "run with --generate-grouped-pre-allocs first" |
| 162 | +``` |
| 163 | + |
| 164 | +#### File Paths in Code |
| 165 | +```diff |
| 166 | +- "fixtures/blockchain_tests_engine_reorg/" |
| 167 | ++ "fixtures/blockchain_tests_engine_x/" |
| 168 | + |
| 169 | +- BlockchainEngineReorgFixture.output_base_dir_name() |
| 170 | ++ BlockchainEngineXFixture.output_base_dir_name() |
| 171 | +``` |
| 172 | + |
| 173 | +## ✅ Verification Checklist |
| 174 | + |
| 175 | +After rebasing, verify: |
| 176 | + |
| 177 | +- [ ] All imports resolve correctly |
| 178 | +- [ ] No references to old class names remain |
| 179 | +- [ ] Command-line flags work with new names |
| 180 | +- [ ] File paths point to correct directories |
| 181 | +- [ ] Error messages use new terminology |
| 182 | +- [ ] Documentation examples are updated |
| 183 | +- [ ] Tests pass with new method names |
| 184 | +- [ ] Linting passes without old terminology warnings |
| 185 | + |
| 186 | +## 🔍 Quick Search Commands |
| 187 | + |
| 188 | +To find remaining old references: |
| 189 | +```bash |
| 190 | +# Find old engine reorg references |
| 191 | +rg "engine.?reorg|enginereorg" --type py |
| 192 | + |
| 193 | +# Find old pre-allocation terminology |
| 194 | +rg "SharedPreState|SharedPreStateGroup|shared_pre_state" --type py |
| 195 | + |
| 196 | +# Find old flags |
| 197 | +rg "generate-shared-pre|use-shared-pre|generate_shared_pre|use_shared_pre" --type py |
| 198 | +``` |
0 commit comments