= Generate JBoss ON Plug-in Pack Update

== Summary

generate-jon-pluginpack-update is a utility to generate a plug-in pack update archive. The utility generates an archive that will eventually be used by customers in a production environment.

The concept is simple. You provide an official plug-in pack and server archive build from the new build that represents the new plug-in pack along with the previous plug-in pack update archive or original GA plug-in pack. You also provide some details about the update including type and a list of new or deleted plug-ins for the update. With that information the utility will construct a new plug-in pack archive that will include all plug-ins from the previous plug-in pack update and any new plug-ins explicitly mentioned along with deleting any old plug-ins that should no longer be included in the plug-in pack.

== How To Use

The utility requires two arguments: _update_number_ and _update_id_.

_update_number_ should represent the sequential update or hotfix version number. In most cases, this will be a value such as `01`, `02`, `03`, etc. However, this can include any value and is not limited to a numeric. It could be, `02-DR01` to denote that this is the first development release for update 02.

_update_number_ will be used as part of the final file name and as the update name in the patch descriptor text file included inside the final update archive.

_update_id_ should represent the bug or task tracking id for which this update is associated. In most cases this is a Bugzilla tracker used to track all fixes and changes included in a specific update.

_update_id_ will be used in the patch descriptor text file included inside the final update archive and can appear on the Red Hat download site. This allows support to easily identify which tracker/task a specific plug-in pack archive is related to.

In addition to the required _update_number_ and _update_id_ arguments, there are other arguments that if omitted, an attempt will be made to determine their value. If their value can not be determined, an error will be raised.

These optional arguments include the new plug-in pack and server archive files along with the update type.

If the plug-in pack archive is not specified on the command line, an attempt will be made to find a file in the current working directory that matches the name pattern `jon-plugin-pack-*-[0-9].[0-9].[0-9].GA.zip`. If a file is not found matching that pattern an error is returned.

As with the plug-in pack archive, the same applies to the server archive if not specified. Its name pattern is `jon-server-[0-9].[0-9].[0-9].GA.zip`. If a file is not found matching the pattern, an error is returned.

=== Passing file names on the command-line

The following command-line demonstrates using the utility to generate EAP plug-in pack update 03 which has associated with tracker Bugzilla 1300725.

----
./generate-jon-pluginpack-update \
  --changeset-file /tmp/pluginupdate/changeset.txt \
  --prev-plug-in-pack-archive /tmp/pluginupdate/jon-plugin-pack-eap-3.3.0.GA-update-02.zip \
  --plug-in-pack-archive /tmp/pluginupdate/jon-plugin-pack-eap-3.3.0.GA-81.zip \
  --server-archive /tmp/pluginupdate/jon-server-3.3.0.GA-81.zip \
  03 \
  1300725
----

* `--changeset-file /tmp/pluginupdate/changeset.txt` indicates that the plug-in file add and delete list is contained in the specified file.
* `--prev-plug-in-pack-archive /tmp/pluginupdate/jon-plugin-pack-eap-3.3.0.GA-update-02.zip` indicates that the contents of  `jon-plugin-pack-eap-3.3.0.GA-update-02.zip` will server as the base for the new plug-in pack update.
* `--plug-in-pack-archive /tmp/pluginupdate/jon-plugin-pack-eap-3.3.0.GA-81.zip` indicates that the contents of `jon-plugin-pack-eap-3.3.0.GA-81.zip` represents the new build of the plug-in pack. Please note however that only the files mentioned in `changeset.txt` specified by the `--changeset-file` argument will be extracted and used in the new plug-in pack update.
* `--server-archive /tmp/pluginupdate/jon-server-3.3.0.GA-81.zip` identifies the server archive associated with this plug-in pack build. The server archive is necessary for version and build information that is extracted and placed in the plug-in pack update's patch descriptor text file.
* `03` represents the update number or sequential update version. In this case, _update-03_.
* `1300725` represents the Bugzilla tracker for this update.

=== Passing URLs on the command-line

Each of the files could have also been specified as an HTTP URL. This allows you to run the utility using artifact URLs for the new build artifacts. For example, using the same example as before but using internal URLs for the necessary archives:

----
./generate-jon-pluginpack-update \
  --changeset-file /tmp/pluginupdate/changeset.txt \
  --prev-plug-in-pack-archive http://download.devel.redhat.com/released/JBossON/3.3/jon-plugin-pack-eap-3.3.0.GA-update-02.zip \
  --plug-in-pack-archive http://download.devel.redhat.com/brewroot/packages/org.jboss.on-jboss-on-parent/3.3.0.GA/81/maven/org/jboss/on/jon-plugin-pack-eap/3.3.0.GA/jon-plugin-pack-eap-3.3.0.GA.zip \
  --server-archive http://download.devel.redhat.com/brewroot/packages/org.jboss.on-jboss-on-parent/3.3.0.GA/81/maven/org/jboss/on/jon-server/3.3.0.GA/jon-server-3.3.0.GA.zip \
  03 \
  1300725
----

If the value passed to `--plug-in-pack-archive` could not be used to deterined the _update type_, it would have been necessary to pass `--update-type eap` as an argument.

=== Using files from working directory

If the server and plug-in pack archives are located in the current work directory and follow the standard naming convention used in JBoss ON, it is not necessary to pass them on the command line.

**NOTE**: If a previous plug-in pack is to be used as the base for the new update, it **MUST** be specified on the command-line.

----
./generate-jon-pluginpack-update \
  --changeset-file ./changeset.txt \
  --prev-plug-in-pack-archive ./jon-plugin-pack-eap-3.3.0.GA-update-02.zip \
  03 \
  1300725
----

From the above command-line, the utility would attempt to locate the server and plug-in pack archives in the current work directory. This could be useful if all necessary artifacts have been downloaded and placed into a specific directory.

=== Other options

For a list of available options, use the --help command-line argument.
