✨ Refactor changelog management: update documentation, remove unused constants, and add comprehensive tests for route configuration

Author: pcrespov

packages/common-library/src/common_library/changelog.py

@@ -1,39 +1,19 @@
+"""
+CHANGELOG formatted-messages for API routes
+
+- Append at the bottom of the route's description
+- These are displayed in the swagger doc
+- These are displayed in client's doc as well (auto-generator)
+- Inspired on this idea https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions
+"""
+
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
 from enum import Enum, auto
-from typing import Any, ClassVar, Final, cast
+from typing import Any, ClassVar, cast
 
 from packaging.version import Version
 
-from ..._meta import API_VERSION
-
-#
-# CHANGELOG formatted-messages for API routes
-#
-# - Append at the bottom of the route's description
-# - These are displayed in the swagger doc
-# - These are displayed in client's doc as well (auto-generator)
-# - Inspired on this idea https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions
-#
-
-# newly created endpoint in given version
-FMSG_CHANGELOG_NEW_IN_VERSION: Final[str] = "New in *version {}*\n"
-
-# changes in given version with message
-FMSG_CHANGELOG_CHANGED_IN_VERSION: Final[str] = "Changed in *version {}*: {}\n"
-
-# marked as deprecated
-FMSG_CHANGELOG_DEPRECATED_IN_VERSION: Final[str] = (
-    "🚨 **Deprecated**: This endpoint is deprecated and will be removed in a future release.\n"
-    "Please use `{}` instead.\n\n"
-)
-
-# marked as deprecated and will be removed in given version
-FMSG_CHANGELOG_REMOVED_IN_VERSION: Final[str] = "Removed in *version {}*: {}\n"
-
-
-DEFAULT_MAX_STRING_LENGTH: Final[int] = 500
-
 
 class ChangelogType(Enum):
     """Types of changelog entries in their lifecycle order"""
@@ -201,6 +181,7 @@ def validate_changelog(changelog: Sequence[ChangelogEntry]) -> None:
 def create_route_config(
     base_description: str = "",
     *,
+    current_version: str | Version,
     changelog: Sequence[ChangelogEntry] | None = None,
 ) -> dict[str, Any]:
     """
@@ -212,6 +193,7 @@ def create_route_config(
 
     Args:
         base_description: Main route description
+        current_version: Current version of the API
         changelog: List of changelog entries indicating version history
 
     Returns:
@@ -222,10 +204,12 @@ def create_route_config(
 
     validate_changelog(changelog_list)
 
+    if isinstance(current_version, str):
+        current_version = Version(current_version)
+
     # Determine endpoint state
     is_deprecated = False
     is_unreleased = False
-    current_version = Version(API_VERSION)
 
     # Get the first entry (NEW) to check if unreleased
     if changelog_list and changelog_list[0].entry_type == ChangelogType.NEW:

…/common-library/tests/test_changelogs.py …s/common-library/tests/test_changelog.pypackages/common-library/tests/test_changelogs.py renamed to packages/common-library/tests/test_changelog.py packages/common-library/tests/test_changelogs.py renamed to packages/common-library/tests/test_changelog.py

@@ -5,9 +5,7 @@
 # pylint: disable=unused-variable
 
 import pytest
-from packaging.version import Version
-from pytest_mock import MockerFixture
-from simcore_service_api_server.api.routes._constants import (
+from common_library.changelog import (
     ChangedEndpoint,
     ChangelogType,
     DeprecatedEndpoint,
@@ -17,20 +15,14 @@
     create_route_description,
     validate_changelog,
 )
+from packaging.version import Version
+from pytest_mock import MockerFixture
 
 
 @pytest.fixture
 def mock_api_version(mocker: MockerFixture) -> str:
     """Fixture to mock the API_VERSION for testing purposes"""
-    import simcore_service_api_server.api.routes._constants
-
-    mock_version = "0.7.0"
-    mocker.patch.object(
-        simcore_service_api_server.api.routes._constants,
-        "API_VERSION",
-        mock_version,
-    )
-    return mock_version
+    return "0.7.0"
 
 
 def test_changelog_entry_types():
@@ -122,7 +114,7 @@ def test_create_route_description():
     assert "Changed in *version 0.6.0*: Added authentication" in desc
 
 
-def test_create_route_config_for_deprecated_endpoints() -> None:
+def test_create_route_config_for_deprecated_endpoints(mock_api_version: str) -> None:
     """Test route configuration for deprecated endpoints"""
     alternative_route = "/v1/new-endpoint"
     changelog = [
@@ -133,6 +125,7 @@ def test_create_route_config_for_deprecated_endpoints() -> None:
     config = create_route_config(
         base_description="This is a deprecated endpoint",
         changelog=changelog,
+        current_version=Version(mock_api_version),
     )
 
     expected_config = {
@@ -159,6 +152,7 @@ def test_create_route_config_for_to_be_released_endpoints(
     config = create_route_config(
         base_description=f"This is a feature coming in version {future_version}",
         changelog=changelog,
+        current_version=Version(mock_api_version),
     )
 
     expected_config = {
@@ -173,7 +167,7 @@ def test_create_route_config_for_to_be_released_endpoints(
     assert config == expected_config
 
 
-def test_create_route_config_with_removal_notice() -> None:
+def test_create_route_config_with_removal_notice(mock_api_version: str) -> None:
     """Test route configuration with explicit removal notice in changelog"""
     removal_message = "Use the new endpoint instead"
     alternative_route = "/v1/better-endpoint"
@@ -187,6 +181,7 @@ def test_create_route_config_with_removal_notice() -> None:
     config = create_route_config(
         base_description="This endpoint will be removed in version 0.9.0",
         changelog=changelog,
+        current_version=Version(mock_api_version),
     )
 
     expected_config = {
@@ -201,13 +196,14 @@ def test_create_route_config_with_removal_notice() -> None:
     assert config == expected_config
 
 
-def test_create_route_config_with_regular_endpoint() -> None:
+def test_create_route_config_with_regular_endpoint(mock_api_version: str) -> None:
     """Test route configuration for a standard endpoint (not deprecated, not upcoming)"""
     changelog = [NewEndpoint("0.5.0")]
 
     config = create_route_config(
         base_description="This is a standard endpoint",
         changelog=changelog,
+        current_version=mock_api_version,
     )
 
     expected_config = {
@@ -222,19 +218,21 @@ def test_create_route_config_with_regular_endpoint() -> None:
     assert config == expected_config
 
 
-def test_create_route_config_with_mixed_changelog() -> None:
-    """Test route configuration with a complex changelog containing multiple entries"""
+def test_create_route_config_with_mixed_changelog(mock_api_version: str) -> None:
+
     alternative_route = "/v1/better-endpoint"
     changelog = [
         NewEndpoint("0.5.0"),
         ChangedEndpoint("0.6.0", "Added authentication"),
+        ChangedEndpoint("0.6.2", "Fixed a bug"),
         DeprecatedEndpoint(alternative_route),
         RemovedEndpoint("0.9.0", "Use the new endpoint instead"),
     ]
 
     config = create_route_config(
         base_description="This endpoint has a complex history",
         changelog=changelog,
+        current_version=mock_api_version,
     )
 
     expected_config = {
@@ -249,10 +247,11 @@ def test_create_route_config_with_mixed_changelog() -> None:
     assert config == expected_config
 
 
-def test_create_route_config_with_empty_changelog() -> None:
-    """Test route configuration with an empty changelog"""
+def test_create_route_config_with_empty_changelog(mock_api_version: str) -> None:
+
     config = create_route_config(
         base_description="This endpoint has no changelog",
+        current_version=mock_api_version,
     )
 
     expected_config = {