Merge pull request #25056 from abpframework/fix/update-dependency-changes-script

improve: preserve doc preamble and normalize `-preview` version in `update_dependency_changes` script

Author: EngincanV

.github/scripts/test_update_dependency_changes.py

@@ -14,7 +14,7 @@
 import os
 sys.path.insert(0, os.path.dirname(__file__))
 
-from update_dependency_changes import merge_changes, render_section
+from update_dependency_changes import merge_changes, render_section, normalize_version, extract_preamble
 
 
 def test_update_then_revert():
@@ -367,12 +367,83 @@ def test_document_format():
     print("-" * 60 + "\n")
 
 
+def test_extract_preamble_with_seo_block():
+    """Test: content with a JSON SEO block before the heading."""
+    print("Test 17: extract_preamble - preamble before heading")
+    content = (
+        "```json\n"
+        "//[doc-seo]\n"
+        "{\n"
+        '    "Description": "Some description."\n'
+        "}\n"
+        "```\n"
+        "\n"
+        "# Package Version Changes\n"
+        "\n"
+        "## 10.1.0-rc.1\n"
+    )
+    result = extract_preamble(content)
+    assert result == "```json\n//[doc-seo]\n{\n    \"Description\": \"Some description.\"\n}\n```\n\n", \
+        f"Unexpected preamble: {repr(result)}"
+    print("✓ Passed: preamble correctly extracted\n")
+
+
+def test_extract_preamble_no_preamble():
+    """Test: heading at the very start — preamble should be empty string."""
+    print("Test 18: extract_preamble - no preamble before heading")
+    content = "# Package Version Changes\n\n## 10.1.0-rc.1\n"
+    result = extract_preamble(content)
+    assert result == "", f"Expected empty string, got: {repr(result)}"
+    print("✓ Passed: empty preamble returned when heading is at start\n")
+
+
+def test_extract_preamble_no_heading():
+    """Test: no matching heading — returns empty string."""
+    print("Test 19: extract_preamble - no matching heading")
+    content = "Some random content without the expected heading.\n"
+    result = extract_preamble(content)
+    assert result == "", f"Expected empty string, got: {repr(result)}"
+    print("✓ Passed: empty string returned when heading is absent\n")
+
+
+def test_normalize_version_preview():
+    """Test: preview suffix is normalized to rc.1."""
+    print("Test 20: normalize_version - preview -> rc.1")
+    assert normalize_version("10.1.0-preview") == "10.1.0-rc.1", \
+        f"Expected '10.1.0-rc.1', got: {normalize_version('10.1.0-preview')}"
+    assert normalize_version("10.2.0-preview") == "10.2.0-rc.1", \
+        f"Expected '10.2.0-rc.1', got: {normalize_version('10.2.0-preview')}"
+    print("✓ Passed: preview correctly normalized to rc.1\n")
+
+
+def test_normalize_version_rc():
+    """Test: rc.N versions are unchanged."""
+    print("Test 21: normalize_version - rc.N unchanged")
+    assert normalize_version("10.1.0-rc.1") == "10.1.0-rc.1", \
+        f"Expected '10.1.0-rc.1', got: {normalize_version('10.1.0-rc.1')}"
+    assert normalize_version("10.2.0-rc.1") == "10.2.0-rc.1", \
+        f"Expected '10.2.0-rc.1', got: {normalize_version('10.2.0-rc.1')}"
+    assert normalize_version("10.2.0-rc.2") == "10.2.0-rc.2", \
+        f"Expected '10.2.0-rc.2', got: {normalize_version('10.2.0-rc.2')}"
+    print("✓ Passed: rc.N versions unchanged\n")
+
+
+def test_normalize_version_stable():
+    """Test: stable versions are unchanged."""
+    print("Test 22: normalize_version - stable unchanged")
+    assert normalize_version("10.1.0") == "10.1.0", \
+        f"Expected '10.1.0', got: {normalize_version('10.1.0')}"
+    assert normalize_version("10.2.0") == "10.2.0", \
+        f"Expected '10.2.0', got: {normalize_version('10.2.0')}"
+    print("✓ Passed: stable versions unchanged\n")
+
+
 def run_all_tests():
     """Run all test cases."""
     print("=" * 70)
     print("Testing update_dependency_changes.py")
     print("=" * 70 + "\n")
-    
+
     test_update_then_revert()
     test_add_then_remove_same_version()
     test_remove_then_add_same_version()
@@ -389,16 +460,24 @@ def run_all_tests():
     test_add_add()
     test_complex_chain_ending_in_original()
     test_document_format()
-    
+    test_extract_preamble_with_seo_block()
+    test_extract_preamble_no_preamble()
+    test_extract_preamble_no_heading()
+    test_normalize_version_preview()
+    test_normalize_version_rc()
+    test_normalize_version_stable()
+
     print("=" * 70)
-    print("All 16 tests passed! ✓")
+    print("All 22 tests passed! ✓")
     print("=" * 70)
     print("\nTest coverage summary:")
     print("  ✓ Basic scenarios (update, add, remove)")
     print("  ✓ Version revert handling")
     print("  ✓ Complex multi-step sequences")
     print("  ✓ Edge cases and duplicates")
     print("  ✓ Document format validation")
+    print("  ✓ Preamble extraction (SEO block, no preamble, no heading)")
+    print("  ✓ Version normalization (preview -> rc.1)")
     print("=" * 70)
 
 

.github/scripts/update_dependency_changes.py

@@ -9,6 +9,22 @@
 DOC_PATH = os.environ.get("DOC_PATH", "docs/en/package-version-changes.md")
 
 
+def extract_preamble(content):
+    """Extract content before the '# Package Version Changes' heading."""
+    header_pattern = re.compile(r"^# Package Version Changes\s*$", re.MULTILINE)
+    match = header_pattern.search(content)
+    if match:
+        return content[: match.start()]
+    return ""
+
+
+def normalize_version(version):
+    """Normalize version string: replace -preview suffix with -rc.1."""
+    if version and version.endswith("-preview"):
+        return version[: -len("-preview")] + "-rc.1"
+    return version
+
+
 def get_version():
     """Read the current version from common.props."""
     try:
@@ -275,7 +291,7 @@ def main():
 
     pr_number = f"#{pr_arg}"
 
-    version = get_version()
+    version = normalize_version(get_version())
     if not version:
         print("Could not read version from common.props.")
         sys.exit(1)
@@ -297,6 +313,7 @@ def main():
 
     # Load existing document from the base branch
     existing_content = get_existing_doc_from_base(base_ref)
+    preamble = extract_preamble(existing_content) if existing_content else ""
     sections = parse_document(existing_content) if existing_content else []
 
     # Find existing section for this version
@@ -320,6 +337,8 @@ def main():
     if doc_dir:
         os.makedirs(doc_dir, exist_ok=True)
     with open(DOC_PATH, "w") as f:
+        if preamble:
+            f.write(preamble)
         f.write(HEADER + "\n")
         for _, text in sections:
             f.write(text.rstrip("\n") + "\n\n")