From 99bfd40717e49793036ef7fbb6e47e1773290f21 Mon Sep 17 00:00:00 2001
From: jjiwooLim <sarah.lim412@gmail.com>
Date: Tue, 7 Nov 2023 15:32:19 -0500
Subject: [PATCH] update installFeature and prepareFeature doc

---
 docs/installFeature.md | 40 ++++++++++++++++++++++++++++++++++++++++
 docs/prepareFeature.md |  6 +++++-
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/docs/installFeature.md b/docs/installFeature.md
index bc8c1bf63..038ee3417 100644
--- a/docs/installFeature.md
+++ b/docs/installFeature.md
@@ -10,17 +10,24 @@ In WebSphere Liberty runtime versions 18.0.0.1 and below, this task will install
 
 In Open Liberty runtime versions 18.0.0.1 and below, this task will be skipped. A warning message will be displayed. The Open Liberty runtime versions 18.0.0.1 and below are bundled with all applicable features. There is no need to install or uninstall additional features.
 
+In Open Liberty runtime versions 21.0.0.11 and above, you can install custom user features. Check this [blog](https://openliberty.io/blog/2022/07/06/user-feature-install.html) on how to build and install user feature using Maven plug-ins.
+
 ### Dependencies
 
 The Liberty Gradle plugin defines the `libertyFeature` dependency configuration for installing features. If the `java` plugin is applied in the build, then the `libertyFeature` configuration extends from the `java` plugin's `compileOnly` configuration to provide Liberty API, SPI, and  Java specification dependencies.
 
 The `libertyFeature` dependency configuration can install features in Liberty runtime versions 18.0.0.2 and above. Use the `io.openliberty.features` group for Open Liberty features, or the `com.ibm.websphere.appserver.features` group for WebSphere Liberty features.
 
+The `featuresBom` dependency configuration is used to install user feature. See [prepareFeature.md](prepareFeature.md) for details.
+
 You need to include `group`, `name`, and `version` values that describes the artifacts to use. An `ext` value for the ESA file type is not required.
 
 ### dependsOn
 `installFeature` depends on `libertyCreate` to evaluate the set of features in the server configuration file.
 
+If the `featuresBom` dependency is configured, then `installFeature` depends on `prepareFeature` to generate `features.json` file for the user feature.
+
+
 ### Properties
 
 See the [Liberty server configuration](libertyExtensions.md#liberty-server-configuration) properties for server related configuration.
@@ -33,6 +40,14 @@ The `installFeature` task uses a `features` extension to define task specific pr
 | acceptLicense | boolean | 1.0 | Accept feature license terms and conditions. The default value is `false`, so you must add this property to get features installed if it is required.  | Required for runtime versions 18.0.0.1 and below, or for features that are not from Open Liberty. <p/> Not required for Open Liberty features on runtime versions 18.0.0.2 and above. |
 | to | String | 1.0 | Specify where to install the feature. The feature can be installed to any configured product extension location, or as a user feature (usr, extension). If this option is not specified the feature will be installed as a user feature. | No |
 | from | String | 1.0 | Specifies a single directory-based repository as the source of the assets. The default is to install from the online Liberty repository. | No |
+| verify | String | X.X | Specifies how features must be verified during a process or an installation. Supported values are `enforce`, `skip`, `all`, and `warn`. If this option is not specified, the default value is enforce. <ul><li>`enforce`: Verifies the signatures of all Liberty features except for user features. It checks the integrity and authenticity of the features that are provided by the Liberty framework.</li><li>`skip`: Choosing this option skips the verification process altogether. No feature signatures are downloaded or checked. It expedites the installation process but must be used with caution, as it bypasses an important security step.</li></ul><ul><li>`all`: Verifies both the Liberty features and the user features. The features that are provided by the Liberty framework and any additional user features or components are checked for integrity.</li><li>`warn`: Similar to the all option, warn also verifies both the Liberty features and user features. This option allows the process to continue, even if some feature signatures cannot be validated. A verification failure does not immediately end the installation process, but it results in a warning message.</li></ul> | No |
+
+Verify your user features by providing the long key ID and key URL to reference your public key that is stored on a key server. For more information about generating a key pair, signing the user feature, and distributing your key, see [Working with PGP Signatures](https://central.sonatype.org/publish/requirements/gpg/#signing-a-file).
+ The following properties can be defined in the `server` extension.
+
+ | Attribute | Type  | Since | Description | Required |
+| --------- | ----- | ----- | ----------- | -------- |
+| keys | Properties | X.x | The property name is used for the keyid, and the property value is used for the keyurl. <ul><li>`keyid`: Provide the long key ID for your public key. The long key ID is a 64-bit identifier that is used to uniquely identify a PGP key.</li><li>`keyurl`: Provide the full URL of your public key. The URL must be accessible and point to a location where your key can be retrieved. The supported protocols for the key URL are `HTTP`, `HTTPS`, and `file`.</li> | No |
 
 ### Examples
 
@@ -112,3 +127,28 @@ liberty {
     }
 }
 ```
+
+5. Install user feature
+
+    1. To install user feature using either the IBM-Shortname or the Subsystem-SymbolicName as the name reference, you first need to run [prepare-feature](prepare-feature.md) task to generate a `features.json` file. To bypass this task, you need to specify the local esa path.
+
+    2. Keep the `featuresBom` dependency from the previous step for your user feature. To verify the signature of your user feature, provide the public key by specifying the `keys` properties in [keyid:keyurl] format. The user feature signature file must reside in the same directory as the corresponding feature esa file.
+    
+    ```xml
+    dependencies {
+        featuresBom 'my.user.features:features-bom:1.0'
+    }
+    liberty {
+        server {
+            features {
+                name = ['myUserFeature-1.0']
+                acceptLicense = true
+                verify = 'all'
+            }
+            keys = ['0x05534365803788CE':'https://keyserver.ubuntu.com/pks/lookup?op=get&amp;options=mr&amp;search=0x05534365803788CE']
+        }
+
+    }
+    
+    ```
+
diff --git a/docs/prepareFeature.md b/docs/prepareFeature.md
index 542a19b0a..8560ef490 100644
--- a/docs/prepareFeature.md
+++ b/docs/prepareFeature.md
@@ -1,10 +1,14 @@
 ## prepareFeature task
----
+
 The `prepareFeature` task  generates `features.json` file for user features. The `features.json` file is JSON file that contains the information found within a feature's ESA manifest file. JSONs are a key requirement for the installation of any Liberty features(s) from a Maven repository. 
 
 
 In Open Liberty and WebSphere Liberty runtime versions 21.0.0.11 and above, this task can prepare the user feature to generate the JSON file.
 
+### Dependencies
+
+The `featuresBom` dependency configuration is used to locate the user feature esa file and to generate `features.json`. The `features.json` is generated in the following maven coordinate: ${userfeature.group}:features:{$userfeature.version}.
+
 
 ### Examples
 1. Place your user feature ESA file in Maven local repository or Maven Central repository.