chore: test: remove shell version of meta-meta compat test

Remove shell-based compatibility test after migration to Python.
Update README with comprehensive documentation for the Python
implementation, including usage examples, test descriptions, and
compatibility handling details.

Author: drmingdrmer

tests/compat/meta_meta/README.md

@@ -1,9 +1,61 @@
 # Test protocol compatibility between latest and old databend-meta
 
+Tests cross-version compatibility of databend-meta, ensuring new versions can communicate with old versions in a cluster.
+
 ## Prerequisites
 
-- Current version of databend-meta must reside in `./bins`:
-    - `./bins/current/databend-meta`
+- Current version binaries must exist in `./bins/current/bin/`:
+    - `databend-meta`
+    - `databend-metactl`
+    - `databend-metabench`
+
+Since building binaries takes several minutes, this is usually done by CI scripts.
+
+## Usage
+
+```bash
+python3 test_meta_meta.py <leader-version> <follower-version>
+```
+
+Examples:
+```bash
+# Test current version with old version
+python3 test_meta_meta.py current 1.2.615
+
+# Test two old versions
+python3 test_meta_meta.py 1.2.615 1.2.600
+```
+
+The script automatically downloads old version binaries from GitHub releases if not present in `./bins/<version>/`.
+
+## Tests
+
+### test_snapshot_replication
+
+Tests snapshot-based replication between versions:
+1. Start leader node, feed data
+2. Trigger snapshot, feed more data
+3. Start follower node (joins via snapshot)
+4. Verify state machine data consistency
+5. Re-import with current metactl and verify again
+
+### test_vote_request
+
+Tests vote request compatibility between versions:
+1. Start two-node cluster with different versions
+2. Feed data, restart cluster
+3. Feed more data, trigger snapshots
+4. Verify state machine data consistency
+
+This test normalizes time precision differences:
+- `time_ms`: truncates last 3 digits to 000
+- `expire_at`: converts milliseconds to seconds
+
+## Compatibility Handling
 
-    Since building a binary takes several minutes,
-    this step is usually done by the calling process, e.g., the CI script.
+The tests account for version differences:
+- **proposed_at_ms**: Removed during comparison (not present in all versions)
+- **Time precision**: Normalized in vote_request test (ms vs sec)
+- **DataHeader**: Excluded from comparison (contains version info)
+- **NodeId**: Excluded from re-import comparison
+- **Expire/GenericKV**: Excluded during re-import (format changed in V002)

tests/compat/meta_meta/test_meta_meta.py

@@ -9,13 +9,30 @@
 import platform
 import re
 import shutil
+import socket
 import subprocess
 import sys
 import time
 import urllib.request
 from pathlib import Path
 
 
+def wait_tcp_port(port: int, timeout: int = 20) -> None:
+    """Wait for TCP port to become available."""
+    print(f" === Waiting for port {port} (timeout: {timeout}s)")
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+                sock.settimeout(1)
+                sock.connect(("127.0.0.1", port))
+                print(f" === Port {port} is ready")
+                return
+        except (socket.error, socket.timeout):
+            time.sleep(0.5)
+    raise TimeoutError(f"Port {port} did not become available within {timeout} seconds")
+
+
 class TestContext:
     """Test environment state and operations."""
 
@@ -65,9 +82,7 @@ def start_node(self, version: str, node_id: int, extra_args: list[str], raft_dir
         print(f" === Running: {' '.join(cmd)}")
         subprocess.Popen(cmd)
 
-        wait_cmd = ["python3", str(self.root_dir / "scripts/ci/wait_tcp.py"), "--timeout", "20", "--port", str(11000 + node_id)]
-        print(f" === Running: {' '.join(wait_cmd)}")
-        subprocess.run(wait_cmd, check=True)
+        wait_tcp_port(11000 + node_id, timeout=20)
         print(f" === databend-meta ver={version} id={node_id} started")
 
     def feed_data(self, node_id: int, number: int = 10) -> None: