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 <[email protected]> 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  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; }
