MPT-18141: rename --fake option to --manual (#43)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

Closes [MPT-18141](https://softwareone.atlassian.net/browse/MPT-18141)

- Rename CLI option `--fake` to `--manual` in the migrate command
- Rename `FakeCommand` class to `ManualCommand` throughout the codebase
- Update migration status enum member from `FAKE_APPLY` to
`MANUAL_APPLIED` with value changed from `"faked"` to `"manual"`
- Rename `Migration.fake()` method to `Migration.manual()` and update
semantics to set `applied_at` timestamp while clearing `started_at`
- Update command factory to route manual migrations through
`ManualCommand`
- Update all error messages and status labels from "fake mode" to
"manual mode"
- Update documentation to reflect manual mode terminology
- Rename and update test cases to use `--manual` flag and verify manual
mode behavior

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

[MPT-18141]:
https://softwareone.atlassian.net/browse/MPT-18141?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: svazquezco

docs/PROJECT_DESCRIPTION.md

@@ -121,7 +121,7 @@ This command creates:
   mpt-service-cli migrate --new-schema "migration_name"
 ```
 
-A new file is created in `migrations/` with a timestamped prefix (e.g., `20260113180013_migration_name.py`) and a prefilled `Command` class.
+A new file is created in `migrations/` with a timestamped prefix (e.g., `20260113180013_migration_name.py`) and a prefilled `Migrate` class.
 
 order_id: timestamp prefix (e.g., `20260113180013`)
 migration_id: user-provided name (e.g., `migration_name`)
@@ -234,14 +234,14 @@ If a migration fails during execution:
 * The started_at timestamp is recorded
 * The applied_at field remains null
 * The error is logged
-* Later runs will retry the failed migration as applied_at is null, unless `--fake` is used to mark it as applied
+* Later runs will retry the failed migration as applied_at is null, unless `--manual` is used to mark it as applied
 
 
-### Fake Mode
+### Manual Mode
 To mark a migration as applied without running it:
 
 ```bash
-  mpt-service-cli migrate --fake MIGRATION_ID
+  mpt-service-cli migrate --manual MIGRATION_ID
 ```
 
 Where `MIGRATION_ID` is the filename without `order_id` and `.py` (e.g., `test1`).
@@ -273,7 +273,7 @@ The status column is derived from the persisted timestamps:
 |-------------|---------------------------------------------------------------|
 | running     | `started_at` is set and `applied_at` is empty                 |
 | failed      | `started_at` and `applied_at` are empty for an existing state |
-| faked       | `started_at` is empty and `applied_at` is set                 |
+| manual      | `started_at` is empty and `applied_at` is set                 |
 | applied     | Both `started_at` and `applied_at` are set                    |
 | not applied | No state entry exists for the migration file                  |
 
@@ -321,7 +321,7 @@ Run `mpt-service-cli --help` to see all available commands and params:
 **Migration fails to run:**
 - Review the error message in the terminal output
 - Check your `Migration.run()` implementation for syntax errors
-- Fix the issue and re-run the migration or use `--fake` to mark it as applied
+- Fix the issue and re-run the migration or use `--manual` to mark it as applied
 
 **NOTE:** There is currently no automatic rollback mechanism. If a migration partially modifies data before failing, you must manually revert those changes or create a new migration to fix the state.
 

make/common.mk

@@ -20,7 +20,7 @@ format:  ## Format code
 	$(RUN) bash -c "ruff check --select I --fix . && ruff format ."
 
 run:  ## Run service
-	$(DC) up
+	$(RUN_IT) bash -c "mpt-service-cli migrate --help && exec bash"
 
 shell:  ## Open Django shell
 	$(RUN_IT) bash -c "swoext shell"

mpt_tool/cli.py

@@ -23,10 +23,10 @@ def migrate(  # noqa: WPS211
     ] = False,
     data: Annotated[bool, typer.Option("--data", help="Run data migrations.")] = False,  # noqa: FBT002
     schema: Annotated[bool, typer.Option("--schema", help="Run schema migrations.")] = False,  # noqa: FBT002
-    fake: Annotated[
+    manual: Annotated[
         str | None,
         typer.Option(
-            "--fake",
+            "--manual",
             help="Mark the migration provided as applied without running it",
             metavar="MIGRATION_ID",
         ),

mpt_tool/commands/factory.py

@@ -6,9 +6,9 @@
 from mpt_tool.commands.check import CheckCommand
 from mpt_tool.commands.data import DataCommand
 from mpt_tool.commands.errors import CommandNotFoundError
-from mpt_tool.commands.fake import FakeCommand
 from mpt_tool.commands.init import InitCommand
 from mpt_tool.commands.list import ListCommand
+from mpt_tool.commands.manual import ManualCommand
 from mpt_tool.commands.new_data import NewDataCommand
 from mpt_tool.commands.new_schema import NewSchemaCommand
 from mpt_tool.commands.schema import SchemaCommand
@@ -39,8 +39,8 @@ def get_instance(cls, param_data: dict[str, bool | str | None]) -> BaseCommand:
                 return DataCommand()
             case {"schema": True}:
                 return SchemaCommand()
-            case {"fake": fake_value} if fake_value is not None:
-                return FakeCommand(migration_id=cast(str, fake_value))
+            case {"manual": manual_value} if manual_value is not None:
+                return ManualCommand(migration_id=cast(str, manual_value))
             case {"new_schema": new_schema_value} if new_schema_value is not None:
                 return NewSchemaCommand(migration_id=cast(str, new_schema_value))
             case {"new_data": new_data_value} if new_data_value is not None:

mpt_tool/commands/fake.py mpt_tool/commands/manual.pympt_tool/commands/fake.py renamed to mpt_tool/commands/manual.py

@@ -4,7 +4,7 @@
 from mpt_tool.use_cases import ApplyMigrationUseCase
 
 
-class FakeCommand(BaseCommand):
+class ManualCommand(BaseCommand):
     """Applies a migration without running it."""
 
     def __init__(self, migration_id: str):
@@ -14,7 +14,7 @@ def __init__(self, migration_id: str):
     @override
     @property
     def start_message(self) -> str:
-        return f"Running migration {self.migration_id} in fake mode."
+        return f"Running migration {self.migration_id} in manual mode."
 
     @override
     @property

mpt_tool/enums.py

@@ -10,7 +10,7 @@ class MigrationStatusEnum(StrEnum):
 
     RUNNING = "running"
     FAILED = "failed"
-    FAKE_APPLY = "faked"
+    MANUAL_APPLIED = "manual"
     APPLIED = "applied"
     NOT_APPLIED = "not applied"
 
@@ -24,7 +24,7 @@ def from_state(cls, migration_state: "Migration | None") -> Self:
         if migration_state.started_at and not migration_state.applied_at:
             return cls.RUNNING
         if migration_state.started_at is None and migration_state.applied_at:
-            return cls.FAKE_APPLY
+            return cls.MANUAL_APPLIED
 
         return cls.FAILED
 

mpt_tool/models.py

@@ -51,8 +51,8 @@ def failed(self) -> None:
         self.started_at = None
         self.applied_at = None
 
-    def fake(self) -> None:
-        """Mark the migration as fake."""
+    def manual(self) -> None:
+        """Mark the migration as manual."""
         self.started_at = None
         self.applied_at = dt.datetime.now(tz=dt.UTC)
 

mpt_tool/use_cases/apply_migration.py

@@ -38,5 +38,5 @@ def execute(self, migration_id: str) -> None:
         if state.applied_at is not None:
             raise ApplyMigrationError(f"Migration {migration_id} already applied")
 
-        state.fake()
+        state.manual()
         self.state_manager.save_state(state)

tests/cli/test_cli.py

@@ -45,19 +45,21 @@ def test_migrate_data_migration_folder_not_found(runner):
     assert "Migration folder not found:" in result.output
 
 
-def test_migrate_fake_folder_not_found(runner):
-    result = runner.invoke(app, ["migrate", "--fake", "not_existing_migration"])
+def test_migrate_manual_folder_not_found(runner):
+    result = runner.invoke(app, ["migrate", "--manual", "not_existing_migration"])
 
     assert result.exit_code == 1, result.output
-    assert "Error running fake command: Migration folder not found: migrations" in result.output
+    assert "Error running manual command: Migration folder not found: migrations" in result.output
 
 
 @pytest.mark.usefixtures("data_migration_file")
-def test_migrate_fake_migration_not_found(runner):
-    result = runner.invoke(app, ["migrate", "--fake", "not_existing_migration"])
+def test_migrate_manual_migration_not_found(runner):
+    result = runner.invoke(app, ["migrate", "--manual", "not_existing_migration"])
 
     assert result.exit_code == 1, result.output
-    assert "Error running fake command: Migration not_existing_migration not found" in result.output
+    assert (
+        "Error running manual command: Migration not_existing_migration not found" in result.output
+    )
 
 
 @freeze_time("2025-04-06 12:21:34")

tests/cli/test_cli_airtable_storage.py

@@ -93,11 +93,11 @@ def test_migrate_data_run_script_fail(mock_airtable, runner, log):
 
 @freeze_time("2025-04-06 10:11:24")
 @pytest.mark.usefixtures("data_migration_file")
-def test_migrate_fake(mock_airtable, runner):
-    result = runner.invoke(app, ["migrate", "--fake", "fake_data_file_name"])
+def test_migrate_manual(mock_airtable, runner):
+    result = runner.invoke(app, ["migrate", "--manual", "fake_data_file_name"])
 
     assert result.exit_code == 0, result.output
-    assert "Running migration fake_data_file_name in fake mode." in result.output
+    assert "Running migration fake_data_file_name in manual mode." in result.output
     assert "Migration fake_data_file_name applied successfully." in result.output
     records = mock_airtable.records.get(("fake_base_id", "fake_table_name"))
     record_key = next(iter(records.keys()))
@@ -111,12 +111,13 @@ def test_migrate_fake(mock_airtable, runner):
 
 
 @pytest.mark.usefixtures("applied_migration", "mock_airtable")
-def test_migrate_fake_migration_already_applied(runner):
-    result = runner.invoke(app, ["migrate", "--fake", "fake_data_file_name"])
+def test_migrate_manual_migration_already_applied(runner):
+    result = runner.invoke(app, ["migrate", "--manual", "fake_data_file_name"])
 
     assert result.exit_code == 1, result.output
     assert (
-        "Error running fake command: Migration fake_data_file_name already applied" in result.output
+        "Error running manual command: Migration fake_data_file_name already applied"
+        in result.output
     )