[sling-org-apache-sling-feature] branch master updated: Add docs about feature archives and framework properties

[cz...@apache.org]

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

cziegeler pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-org-apache-sling-feature.git


The following commit(s) were added to refs/heads/master by this push:
     new 1bd2e4e  Add docs about feature archives and framework properties
1bd2e4e is described below

commit 1bd2e4ec9236f04aebe2cda044c7d1420e1f0dfe
Author: Carsten Ziegeler <cz...@apache.org>
AuthorDate: Fri Mar 27 08:19:47 2020 +0100

    Add docs about feature archives and framework properties
---
 docs/feature-archives.md | 15 ++++++++++++++-
 docs/features.md         | 13 ++++++++++++-
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/docs/feature-archives.md b/docs/feature-archives.md
index d00051e..ebada3d 100644
--- a/docs/feature-archives.md
+++ b/docs/feature-archives.md
@@ -1,3 +1,16 @@
 # Feature Archives
 
-TBD
+A feature file contains only references to artifacts like bundles. There are some use cases where it is useful to distribute a feature with all its artifacts, for example when distributing a feature to downstream users or when distributing a complete OSGi application. This can be done through feature archives.
+
+A feature archive is an uncompressed zip file which contains one or more features together with the artifacts. The zip file uses the jar file format and has a manifest as the first entry in the archive. The manifest must contain these headers:
+
+* 'Feature-Archive-Version' : The version of the format of the feature archive. Currently the value of this must be *1*.
+* 'Feature-Archive-Contents' : The features contained in this archive. This is a comma separated list containing Maven ids or Maven urls.
+
+All artifacts including the features are written to the archive in a maven repository like structure, that is the group id is converted to a path, the next path segment is the artifact id, followed by a path segment for the version. And the actual files are written into that directory with the typical maven convention. For example a feature with the id *org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0* containing a bundle with the id *org.apache.sling:org.apache.slin [...]
+
+```
+/ META-INF / MANIFEST.MF
+/ org / apache / sling / org.apache.sling.core.feature / 1.0.0 / org.apache.sling.core.feature-1.0.0.slingosgifeature
+                       / org.apache.sling.api / 2.3.0 / org.apache.sling.api-2.3.0.jar
+```
diff --git a/docs/features.md b/docs/features.md
index eb438b0..def3c19 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -101,7 +101,18 @@ A feature with configurations:
 
 ## OSGi Framework properties
 
-TBD
+Apart from OSGi configurations, sometimes OSGi framework properties are used for configurations. Framework properties are key value pairs where the value is a string. They can be specified with the 'framework-properties' key in the feature:
+
+```
+A feature with framework properties:
+{
+  "id" : "org.apache.sling:org.apache.sling.core.feature:slingosgifeature:1.0.0",
+  "framework-properties" : {
+    "org.apache.sling.logging.default.level" : "DEBUG",
+    "org.apache.felix.framework.cache"  : "true"
+  }
+}
+```
 
 ## Requirements and Capabilities