[celix] 01/02: Adds svc version documentation

[pn...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

pnoltes pushed a commit to branch feature/update_component_and_pattern_documentation
in repository https://gitbox.apache.org/repos/asf/celix.git

commit 785b519ab8cc0178097a501e7ae1e20ff0de052b
Author: Pepijn Noltes <pn...@apache.org>
AuthorDate: Sun May 8 22:39:36 2022 +0200

    Adds svc version documentation
---
 documents/README.md               |  5 +++--
 documents/components.md           | 17 ++++++++++++++++-
 documents/services.md             | 40 +++++++++++++++++++++++++++++++++++++++
 libs/utils/src/celix_file_utils.c |  2 +-
 4 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/documents/README.md b/documents/README.md
index 235626aa..af495bb1 100644
--- a/documents/README.md
+++ b/documents/README.md
@@ -82,8 +82,9 @@ bundles contains binaries depending on the stdlibc++ library.
 * Framework 
   * [Apache Celix Bundles](bundles.md)
   * [Apache Celix Services](services.md)
-  * [Apache Celix Components](components.md) 
+  * [Apache Celix Components](components.md) TODO rewrite
   * [Apache Celix Framework](framework.md)
   * [Apache Celix Containers](containers.md)
+* [OSGi patterns in Apache Celix](patterns.md) TODO
 * [Apache Celix CMake Commands](cmake_commands)
-* [Apache Celix - Getting Started Guide](getting_started) 
+* [Apache Celix - Getting Started Guide](getting_started) TODO rewrite
diff --git a/documents/components.md b/documents/components.md
index f0dcb5dc..3421e1b0 100644
--- a/documents/components.md
+++ b/documents/components.md
@@ -21,7 +21,22 @@ limitations under the License.
 
 # Apache Celix Components
 
-TODO refactor this documentation file
+Apache Celix also supports component-oriented development with a focus on dynamic components which can
+provide and require Apache Celix services.  
+
+Components can be created by using the Apache Celix Dependency Manager. 
+
+Note that the Apache Celix Dependency Manager is inspired by the 
+[Apache Felix Dependency Manager](https://felix.apache.org/documentation/subprojects/apache-felix-dependency-manager.html) 
+and the Apache Felix Dependency Manager way chosen as inspiration instead of the OSGi SCR,
+because of it originally focus on creating declarative components in code instead of configuration (XML) 
+or annotations.
+
+
+
+
+
+
 
 ## Introduction
 
diff --git a/documents/services.md b/documents/services.md
index ae7e17bd..7015d2d5 100644
--- a/documents/services.md
+++ b/documents/services.md
@@ -625,3 +625,43 @@ Service tracker callback with a synchronized service registration
 ![Register Service Async](diagrams/services_tracker_services_rem_seq.png)
 Service tracker callback with a synchronized service un-registration
 ---
+
+## Service versions
+Apache Celix services can be versioned using the `service.version` property.
+When versioning services [semantic versions](https://semver.org) should be used.
+
+A backward incompatible change should lead to a major version increase (e.g. 1.0.0 -> 2.0.0), 
+a backward compatible change should lead to minor version increase (e.g. 1.0.0 -> 1.1.) and insignificant
+change or bug fix should lead to a micro version increase (e.g. 1.0.0 -> 1.0.1). 
+
+### Semantic versioning for C services
+For a C Service versioning can be used to express binary compatibility (for the same platform / compiler),
+
+Backwards incompatible (major) updates: 
+- Removing a function.
+- Adding a function before any other function.
+- Moving a function to another position in the service struct.
+- Changing the signature of a function
+- Changing the semantics of an argument (e.g. changing unit of measurement of an argument from "kilometers" to "meters") or function.
+
+A backwards binary compatible change which extend the functionality should lead to a minor version increase (e.g. 1.0.0 -> 1.1.0).
+Backwards (minor) compatible updates:
+- Adding a function to the back of the service struct.
+
+A backwards binary compatible change which does not extend the functionality should lead to a micro version increase (e.g. 1.0.0 -> 1.0.1).
+Changes considered backwards binary compatible which does not extend the functionality are:
+- Changes in the documentation.
+- Renaming of arguments.
+
+### Semantic versioning for C++ services
+For C++ Services versioning should only be used to express source compatibility, because binary 
+compatibility in C++ if difficult and should be avoided. 
+
+Backwards incompatible (major) updates:
+- Removing a method,
+- Changing the signature of a method, 
+- Changing the semantics of an argument (e.g. changing unit of measurement of an argument from "kilometers" to "meters") or method.
+
+Backwards (minor) compatible updates:
+- Changing the signature of a method by extending arguments and specifying defaults.  
+- Adding a method.
diff --git a/libs/utils/src/celix_file_utils.c b/libs/utils/src/celix_file_utils.c
index aeafdb80..d1e35ae7 100644
--- a/libs/utils/src/celix_file_utils.c
+++ b/libs/utils/src/celix_file_utils.c
@@ -235,7 +235,7 @@ celix_status_t celix_utils_extractZipFile(const char* zipPath, const char* extra
         status = celix_utils_extractZipInternal(zip, extractToDir, errorOut);
         zip_close(zip);
     } else {
-        //note libzip can give more info with zip_error_to_str if needed (but this requires a allocated string buf).
+        //note libzip can give more info with zip_error_to_str if needed (but this requires an allocated string buf).
         status = CELIX_FILE_IO_EXCEPTION;
         *errorOut = ERROR_OPENING_ZIP;
     }