docs: introduce api lifecycle

docs/advanced_usage/api_lifecycle.rst

@@ -0,0 +1,115 @@
+.. _api_lifecycle:
+
+API Lifecycle
+=============
+
+To ensure a set of stable APIs, we introduced an API lifecycle.
+This will allow us to introduce/incubate new features while keeping
+the stable one up and running.
+
+Principle to work for
+---------------------
+
+If we extend our existing functionalities while following the
+`open-closed <https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle>`_
+principle, there should not be any breaking changes visible to our users.
+
+But as you all know, it is not that simple. Ensuring backward compatibilities is
+directly impacting **maintainability** in the following ways:
+
+* code we do not delete needs to be maintained (unittests and doc included)
+* legacy APIs may include switch cases in new APIs
+* legacy APIs may include dependencies to classes or modules we do not need
+
+
+Different use-cases
+-------------------
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Use-case
+     - User expectations
+     - Size of the complexity
+   * - Refinement of a functionality
+     - stable APIs
+     - medium
+   * - Refactoring activities of a functionality
+     - stable APIs
+     - medium
+   * - Incubation of a new functionality
+     - unstable APIs
+     - big
+
+API States
+----------
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - State
+     - Description
+   * - stable
+     - The API is stable and will not change in the future
+   * - incubation
+     - The API is not stable and may change in the future
+   * - deprecated
+     - The API is not recommended for use and may be removed in the future
+   * - removed
+     - The API is removed and no longer available
+
+Approach
+--------
+
+**Contribution of a new module**
+
+#. In `src/pykiso/lib/incubation` are two folders, one dedicated for the incubation of `auxiliaries` and the other for `connectors`.
+#. Depending on the type of module you want to contribute (:ref:`how_to_create_connector` or :ref:`how_to_create_aux`), create a module in the right folder.
+#. Do not forget the unittests (same location of all unittests).
+#. Do not forget to add your module to the documentation. Also add a `warning` section to inform the user that this module is in incubation phase.
+#. Do not forget to add an usage example for your module.
+
+**Refactoring of an existing module**
+
+#. In `src/pykiso/lib/incubation` are two folders, one dedicated for the incubation of `auxiliaries` and the other for `connectors`.
+#. Copy the module to refactor to the right folder.
+#. Update/Refactor the APIs. Breaking the Api is fine in Incubation.
+#. In the old location, if possible, inherit from it and replace the content of the legacy APIs. There should be no breaking changes,
+   this step is to support backward compatibility.
+#. In the documentation, extend the already existing .rst file with a warning specifying which APIs are in `incubation` / refactored and which one will be `deprecated`
+   and removed in the next major release.
+#. Extend the unittests to test the refactored APIs. Old tests should not be touched, they ensure the backward compatibility.
+#. Do not forget the warning.
+#. Users can access the new functionalities with from ebplugins.incubation.emb_aux the APIs with breaking changes.
+#. Update the examples to use the new API.
+
+**Deprecation of an existing module**
+
+#. In the documentation, add a `deprecation` warning to the APIs.
+#. In case of a module, add a `deprecation` warning to the module.
+
+
+Versioning
+----------
+
+Like for any other changes, we will be using `conventional commits <https://www.conventionalcommits.org/en/v1.0.0/>`_.
+
+The versioning will be done according to the `semantic versioning <https://semver.org/>`_.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Version
+     - Changes to expect
+   * - patch
+     - no breaking changes, no new incubation feature, no deprecation
+   * - minor
+     - no breaking changes in stable code, breaking changes for incubation features, new incubation feature, deprecation of an existing feature, move of an incubation feature to stable
+   * - major
+     - breaking changes, new incubation feature, deletion of deprecated feature
+
+
+ref: https://www.sebastianpfischer.com/index.php/2023/02/21/how-to-deal-with-breaking-changes-python/

docs/advanced_usage/index.rst

@@ -10,6 +10,7 @@ Advanced Usage
     dynamic_conf
     remote_test
     reporting
+    api_lifecycle
     how_to_auxiliary
     how_to_connector
     how_to_change_logger_class

docs/auxiliaries/index.rst

@@ -12,7 +12,6 @@ Existing Auxiliaries
     communication_auxiliary
     dut_auxiliary
     instrument_control_auxiliary
-    mp_proxy_auxiliary
     proxy_auxiliary
     record_auxiliary
     simulated_auxiliary

docs/connectors/CChannels/cc_grpc_client.rst

@@ -1,6 +1,9 @@
 cc_grpc_client
 ==============
 
-.. automodule:: pykiso.lib.connectors.cc_grpc_client
+.. warning::
+    In incubation state.
+
+.. automodule:: pykiso.lib.incubation.connectors.cc_grpc_client
     :members:
     :private-members:

docs/connectors/CChannels/index.rst

@@ -10,7 +10,6 @@ Included Connectors
     cc_base_interface
     cc_example
     cc_fdx_lauterbach
-    cc_mp_proxy
     cc_pcan_can
     cc_proxy
     cc_raw_loopback

docs/introduction/integration_test.rst

@@ -107,8 +107,6 @@ Existing Auxiliarys
 
 :ref:`instrument_control_auxiliary` - interface to arbitrary instrument (e.g. power supplies).
 
-:ref:`auxiliaries/mp_proxy_auxiliary:mp_proxy_auxiliary` - multiprocessing proxy auxiliary
-
 :ref:`auxiliaries/proxy_auxiliary:proxy_auxiliary` - connect multiple auxiliaries to one unique connector.
 
 :ref:`auxiliaries/record_auxiliary:record_auxiliary` - logging from connector.

examples/grpc.yaml

@@ -14,7 +14,7 @@ connectors:
       default_rpc_name: "SayHello"
       default_message_name: "HelloRequest"
       default_message_fields: {"name": "World"}
-    type: pykiso.lib.connectors.cc_grpc_client:CCGrpcClient
+    type: pykiso.lib.incubation.connectors.cc_grpc_client:CCGrpcClient
 
 test_suite_list:
 - suite_dir: test_suite_grpc

src/pykiso/lib/auxiliaries/can_auxiliary.py

@@ -41,6 +41,7 @@ def __init__(self, com: CChannel, dbc_file: str, **kwargs):
         """Constructor.
 
         :param com: CChannel that supports raw communication over CAN
+        :param dbc_file: dbc file that provides the can messages structure
         """
         self.tx_task_on = False
         super().__init__(is_proxy_capable=True, tx_task_on=True, rx_task_on=True, **kwargs)
@@ -98,6 +99,7 @@ def _receive_message(self, timeout_in_s: float = 0.1) -> None:
 
     def get_last_message(self, message_name: str) -> Optional[CanMessage]:
         """Get the last message which has been received on the bus.
+
         :param message_name: name of the message, you want to get
 
         :return: last can massage or return none if the message, or return none if message is not occur
@@ -112,7 +114,9 @@ def get_last_message(self, message_name: str) -> Optional[CanMessage]:
 
     def get_last_signal(self, message_name: str, signal_name: str) -> Optional[Any]:
         """Get the last message which has been received on the bus.
+
         :param message_name: name of the message, you want to get
+        :param signal_name: name of the signal, you want to get
 
         :return: last can massage or return none if the message or return none if message or signal is not occur
         """
@@ -127,8 +131,9 @@ def get_last_signal(self, message_name: str, signal_name: str) -> Optional[Any]:
 
     def wait_for_message(self, message_name: str, timeout: float = 0.2) -> dict[str, any]:
         """Get the last message with certain timeout in seconds.
+
         :param message_name: name of the message to receive
-        :param timeout time to wait till a message receives in seconds
+        :param timeout: time to wait till a message receives in seconds
 
         :return: list of last can messages or None if no messages for this component
         """
@@ -156,12 +161,11 @@ def wait_to_match_message_with_signals(
         expected_signals: dict[str, any],
         timeout: float = 0.2,
     ) -> dict[str, any]:
-        """Get first message which matches the patter of signals
-        .
+        """Get first message which matches the patter of signals.
 
         :param message_name: name of the message to receive
         :param expected_signal: list of expected signals to match with message
-        :param timeout time to wait till a message receives in seconds
+        :param timeout: time to wait till a message receives in seconds
 
         :return: list of last can messages or None if no messages for this component
         """

src/pykiso/lib/incubation/__init__.py

@@ -0,0 +1,18 @@
+##########################################################################
+# Copyright (c) 2023-2024 Accenture GmbH
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0.
+#
+# SPDX-License-Identifier: EPL-2.0
+##########################################################################
+
+"""
+Incubation
+**********
+
+:module: incubation
+
+.. currentmodule:: incubation
+
+"""

src/pykiso/lib/incubation/auxiliaries/__init__.py

@@ -0,0 +1,18 @@
+##########################################################################
+# Copyright (c) 2023-2024 Accenture GmbH
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0.
+#
+# SPDX-License-Identifier: EPL-2.0
+##########################################################################
+
+"""
+Collection of auxiliaries in incubation phase
+*********************************************
+
+:module: incubation.auxiliaries
+
+.. currentmodule:: incubation.auxiliaries
+
+"""

src/pykiso/lib/incubation/connectors/__init__.py

@@ -0,0 +1,18 @@
+##########################################################################
+# Copyright (c) 2023-2024 Accenture GmbH
+# This program and the accompanying materials are made available under the
+# terms of the Eclipse Public License 2.0 which is available at
+# http://www.eclipse.org/legal/epl-2.0.
+#
+# SPDX-License-Identifier: EPL-2.0
+##########################################################################
+
+"""
+Collection of connectors in incubation phase
+********************************************
+
+:module: incubation.connectors
+
+.. currentmodule:: incubation.connectors
+
+"""

tests/test_cc_grpc_client.py

@@ -18,7 +18,7 @@
 # Import the generated protobuf files
 from grpc_test_files import helloworld_pb2, helloworld_pb2_grpc
 
-from pykiso.lib.connectors.cc_grpc_client import CCGrpcClient
+from pykiso.lib.incubation.connectors.cc_grpc_client import CCGrpcClient
 
 
 class Greeter(helloworld_pb2_grpc.GreeterServicer):

tests/test_show_tag.py

@@ -67,7 +67,7 @@ def tmp_yaml_files(tmp_path: Path, request):
 
 @pytest.fixture
 def basic_test_mock(mocker):
-    return mocker.patch("pykiso.test_coordinator.test_case.BasicTest")
+    return mocker.patch("pykiso.tool.show_tag.BasicTest")
 
 
 @pytest.fixture(autouse=True, scope="module")