Github user ottobackwards commented on a diff in the pull request:
https://github.com/apache/metron/pull/774#discussion_r151198323
--- Diff: bundles-maven-plugin/README.md ---
@@ -0,0 +1,230 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+# Apache Metron Bundle Maven Plugin
+
+Apache Metron Bundles Maven Plugin helps to build Bundles Archives to
support the classloader isolation model.
+
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Building](#building)
+- [Getting Stared](#getting_started)
+- [Getting Help](#getting-help)
+- [License](#license)
+
+## Requirements
+* JDK 1.7 or higher
+* Apache Maven 3.1.0 or higher
+
+## Building
+
+Building the bundles-maven-plugin module should be rare since it will be
released infrequently compared to
+the main 'metron' code tree.
+
+- Build with `mvn clean install`
+- Presuming you need to make use of changes to the bundles-maven-plugin
module, you should next
+ go to the [metron](../metron) directory and follow its instructions.
+
+## Getting Started
+
+While it is most likely
+that a maven archetype is being utilized to create bundles, as part of a
toolkit etc, you may want to create on manually, or may need to create a
project for use in an archetype.
+
+The plugin is utilized by setting the packaging of a maven module to
'bundle'.
+
+```xml
+<packaging>bundle</packaging>
+```
+
+This means that when you package this module, any of it's non-provided
dependencies will be packaged into the produced bundle ( and all of their
non-provided dependencies as well).
+Since a library may not always be distributed as part of a bundle with all
it's dependencies, the bundle module
+shall be a separate module from the actual classes and dependencies to be
bundled.
+
+A very simple example layout for a project that utilizes bundles would be:
+
+```bash
+âââ README.md
+âââ pom.xml
+âââ testapp
+â  âââ pom.xml
+â  âââ src
+â  â  âââ main
+â  â  â  âââ java
+â  â  â  âââ org
+â  â  â  âââ apache
+â  â  â  âââ test
+â  â  â  âââ App.java
+â  â  âââ test
+â  â  âââ java
+â  â  âââ org
+â  â  âââ apache
+â  â  âââ test
+â  â  âââ AppTest.java
+âââ testappbundle
+ âââ pom.xml
+```
+Where testappbundle is the bundle module that creates a bundle of testapp,
and contains the following pom.xml:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd";>
+ <parent>
+ <artifactId>test.bundles.plugin</artifactId>
+ <groupId>org.apache.test</groupId>
+ <version>1.0-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>test.app.bundle</artifactId>
+
+ <!-- Packaging is bundle -->
+ <packaging>bundle</packaging>
+
+ <!-- All dependencies of this module, and all the dependencies of THAT
dependency will
+ be included in the produced bundle -->
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.test</groupId>
+ <artifactId>test.app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <!-- OUR PLUGIN REFERENCES -->
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.metron</groupId>
+ <artifactId>bundles-maven-plugin</artifactId>
+ <version>0.4.2</version>
+ <extensions>true</extensions>
+ <configuration>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.metron</groupId>
+ <artifactId>bundles-maven-plugin</artifactId>
+ <version>0.4.2</version>
+ <extensions>true</extensions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+```
+When the module is packaged, it packages all of it's non-provided
dependencies into the bundles /bundled-dependencies directory.
+Thus, to create a bundle of a module's jar and that jar's non-provided
dependencies, you add that module to your
+bundle modules dependencies. You can unzip and examine the bundle in the
target directory, and verify
+it's contents, which should be similar to :
+
+```bash
+-> % tree .
+.
+âââ META-INF
+ âââ MANIFEST.MF
+ âââ bundled-dependencies
+ â  âââ log4j-1.2.17.jar
+ â  âââ metron-common-0.4.1.jar
+ â  âââ slf4j-api-1.7.7.jar
+ â  âââ slf4j-log4j12-1.7.7.jar
+ â  âââ test.app-1.0-SNAPSHOT.jar
+ âââ maven
+ âââ org.apache.test
+ âââ test.app.bundle
+ âââ pom.properties
+ âââ pom.xml
+```
+
+This reflects the testapp project, which has these dependencies :
+
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.apache.metron</groupId>
+ <artifactId>metron-common</artifactId>
+ <version>0.4.1</version>
+ </dependency>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>3.8.1</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+```
+metron-common itself is a shaded jar, but it depends on log4j and slf4j,
so those libraries are pulled in..
+
+## Quickstart
+
+* Create a new multi module maven project (if you do not have one already)
+* Add a new module for your bundle, it needs only to have a pom.xml
+* Create the pom.xml as above, with the correct plugin and packaging
entries, and add dependencies
+for the module you want to bundle.
+* `mvn package`
--- End diff --
no problem, let me know if the new doc is in line with what you are looking
for
---
