Merge "Move plugin underneath 'its' package hierarchy"
diff --git a/BUCK b/BUCK
index 551de44..52612c3 100644
--- a/BUCK
+++ b/BUCK
@@ -12,7 +12,7 @@
'Implementation-Vendor: GerritForge LLP',
],
deps = [
- '//plugins/its-base:its-base__plugin',
+ ':its-base_stripped',
'//plugins/its-rtc/lib:commons-logging',
],
provided_deps = [
@@ -24,6 +24,37 @@
],
)
+def strip_jar(
+ name,
+ src,
+ excludes = [],
+ visibility = [],
+ ):
+ name_zip = name + '.zip'
+ genrule(
+ name = name_zip,
+ cmd = 'cp $SRCS $OUT && zip -qd $OUT ' + ' '.join(excludes),
+ srcs = [ src ],
+ deps = [ src ],
+ out = name_zip,
+ visibility = visibility,
+ )
+ prebuilt_jar(
+ name = name,
+ binary_jar = ':' + name_zip,
+ visibility = visibility,
+ )
+
+strip_jar(
+ name = 'its-base_stripped',
+ src = '//plugins/its-base:its-base',
+ excludes = [
+ 'Documentation/about.md',
+ 'Documentation/build.md',
+ 'Documentation/config-connectivity.md',
+ ]
+)
+
java_test(
name = 'its-rtc_tests',
srcs = glob(['src/test/java/**/*.java']),
diff --git a/src/main/resources/Documentation/about.md b/src/main/resources/Documentation/about.md
new file mode 100644
index 0000000..0b9d084
--- /dev/null
+++ b/src/main/resources/Documentation/about.md
@@ -0,0 +1,6 @@
+`@PLUGIN@` is an [`its-base`][its-base] based plugin that (based on
+events in Gerrit) allows to take actions in IBM Rational Team Concert
+(RTC). For example, it can add comments to bugs, or change status of
+bugs.
+
+[its-base]: https://gerrit-review.googlesource.com/#/admin/projects/plugins/its-base
\ No newline at end of file
diff --git a/src/main/resources/Documentation/config-connectivity.md b/src/main/resources/Documentation/config-connectivity.md
new file mode 100644
index 0000000..1bde3f6
--- /dev/null
+++ b/src/main/resources/Documentation/config-connectivity.md
@@ -0,0 +1,85 @@
+RTC connectivity
+================
+
+In order for @PLUGIN@ to connect to RTC instance, url and credentials
+are required in your site's `etc/gerrit.config` or `etc/secure.config`
+under the `@PLUGIN@` section.
+
+Example:
+
+```
+[@PLUGIN@]
+ url=http://my.rtc.instance.example.org
+ username=USERNAME_TO_CONNECT_TO_RTC
+ password=PASSWORD_FOR_ABOVE_USERNAME
+```
+
+HTTP/S and network settings
+---------------------------
+
+There are no additional settings required for a default connectivity from Gerrit
+to RTC and the default JVM settings are automatically taken for opening outbound
+connections.
+
+However connectivity to RTC could be highly customised for defining the protocol
+security level, pooling and network settings. This allows the administrator to
+have full control of the output pipe to RTC and the propagation of the Change
+events to the associated issues in a high-loaded production environment.
+
+All settings are defined in gerrit.config under the same `[@PLUGIN@]` section.
+See below the list of the most important parameters and their associated
+meaning.
+
+`sslVerify`
+: `true` or `false`. When using HTTP/S to connect to RTC (the most typical
+ scenario) allows to enforce (recommended) or disable
+ ( **ONLY FOR TEST ENVIRONMENTS** ) the X.509 Certificates validation during
+ SSL handshake. If unsure say `true`.
+
+`httpSocketTimeout`
+: `<number>` Defines the socket timeout in milliseconds,
+ which is the timeout for waiting for data or, put differently,
+ a maximum period inactivity between two consecutive data packets).
+ A timeout value of zero is interpreted as an infinite timeout.
+
+`httpSocketBufferSize`
+: `<number>` Determines the size of the internal socket buffer used to
+ buffer data while receiving / transmitting HTTP messages.
+
+`httpSocketReuseaddr`
+: `true` or `false`. Defines whether the socket can be bound even though a
+ previous connection is still in a timeout state.
+
+`httpConnectionTimeout`
+: `<number>` Determines the timeout in milliseconds until a connection is
+ established. A timeout value of zero is interpreted as an infinite timeout.
+
+`httpConnectionStalecheck`
+: `true` or `false`. Determines whether stale connection check is to be
+ used. The stale connection check can cause up to 30 millisecond overhead per
+ request and should be used only when appropriate. For performance critical
+ operations this check should be disabled.
+
+`httpSocketKeepalive`
+: `true` or `false`. Defines whether or not TCP is to send automatically
+ a keepalive probe to the peer after an interval of inactivity (no data
+ exchanged in either direction) between this host and the peer. The purpose
+ of this option is to detect if the peer host crashes.
+
+`httpConnManagerTimeout`
+: `<number>` Defines the timeout in milliseconds used when retrieving a free
+ connection from the pool of outbound HTTP connections allocated.
+
+`httpConnManagerMaxTotal`
+: `<number>` Defines the maximum number of outbound HTTP connections in total.
+ This limit is interpreted by client connection managers and applies to
+ individual manager instances.
+
+**NOTE**: The full list of all available HTTP network connectivity parameters can be found under
+the [Apache Commons HTTP Client 4.3.x documentation](http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/index.html?org/apache/http/client/params/ClientPNames.html). Gerrit parameters names are the [CamelCase](http://en.wikipedia.org/wiki/Camelcase) version of the string
+values of the Apache HTTP Client ones.
+
+
+[Back to @PLUGIN@ documentation index][index]
+
+[index]: index.html
diff --git a/src/main/resources/Documentation/config.md b/src/main/resources/Documentation/config.md
deleted file mode 100644
index 65d30a3..0000000
--- a/src/main/resources/Documentation/config.md
+++ /dev/null
@@ -1,264 +0,0 @@
-Plugin @PLUGIN@
-===============
-
-This plugin allows to associate IBM Rational Team Concert (RTC) issues to Git commits / Gerrit
-Changes using the Gerrit ChangeListener and CommitValidator interfaces.
-
-Main integration points provided are:
-
-1. Commit validation (synchronous). It is the ability to introduce an additional validation
-step to the Git commits pushed to Gerrit either directly to the target branch or submitted
-for Code Review.
-2. Commit association and workflow (asynchronous). It is the bi-directional integration between
-the RTC issue and its corresponding Git commit / Gerrit Change. Additionally the workflow of
-the RTC issue and Gerrit Review can be linked together using an external actions mapping file.
-3. Configuration of comment links (init). It is an additional step included in the Gerrit init
-configuration that allows to configure the RTC issue syntax and formatting all the references
-rendered in Gerrit as hyperlinks to the corresponding issue target URL in RTC.
-
-It can be configured per project whether the RTC integration is
-enabled or not. To enable the RTC integration for a project the
-project must have the following entry in its `project.config` file in
-the `refs/meta/config` branch:
-
-```
- [plugin "its-rtc"]
- enabled = true
-```
-
-If `plugin.its-rtc.enabled` is not specified in the `project.config` file
-the value is inherited from the parent project. If it is also not set
-on any parent project the RTC integration is disabled for this
-project.
-
-By setting `plugin.its-rtc.enabled` to true in the `project.config` of the
-`All-Projects` project the RTC integration can be enabled by default
-for all projects. During the initialization of the plugin you are asked
-if the RTC integration should be enabled by default for all projects
-and if yes this setting in the `project.config` of the `All-Projects`
-project is done automatically.
-
-If child projects must not be allowed to disable the RTC integration
-a project can enforce the RTC integration for all child projects by
-setting `plugin.its-rtc.enabled` to `enforced`.
-
-On the project info screen there is a dropdown list for the
-`plugin.its-rtc.enabled` parameter which offers the values `true`,
-`false`, `enforced` and `INHERIT`. Project owners can change this
-parameter and save it. If the RTC integration is enforced by a parent
-project the dropdown list is disabled.
-
-The RTC integration can be limited to specific branches by setting
-`plugin.its-rtc.branch`. The branches may be configured using explicit
-branch names, ref patterns, or regular expressions. Multiple branches
-may be specified.
-
-E.g. to limit the RTC integration to the `master` branch and all
-stable branches the following could be configured:
-
-```
- [plugin "its-rtc"]
- enabled = true
- branch = refs/heads/master
- branch = ^refs/heads/stable-.*
-```
-
-Comment links
-----------------
-
-Git commits are associated to RTC issues reusing the existing Gerrit
-[commitLink configuration][1] to extract the issue ID from commit comments.
-
-[1]: ../../../Documentation/config-gerrit.html#__a_id_commentlink_a_section_commentlink
-
-Additionally you need to specify the enforcement policy for git commits
-with regards to issue-tracker associations; the following values are supported:
-
-`MANDATORY`
-: One or more issue-ids are required in the git commit message, otherwise
- the git push will be rejected.
- NOTE: triggers a *synchronous API call* to RTC for the issue-id lookup, push
- is blocked until the operation is completed.
-
-`SUGGESTED`
-: Whenever git commit message does not contain one or more issue-ids,
- a warning message is displayed as a suggestion on the client.
- NOTE: triggers a *synchronous API call* to RTC for the issue-id lookup, push
- is blocked until the operation is completed.
-
-`OPTIONAL`
-: Issues-ids are liked when found on git commit message, no warning are
- displayed otherwise.
-
-**Example:**
-
- [commentLink "its-rtc"]
- match = RTC#([0-9]*)
- html = "<a href=\"https://rtc.gerritforge.com:9443/ccm/browse/$1\">$1</a>"
- association = OPTIONAL
-
-Once a Git commit with a comment link is detected, the RTC issue ID
-is extracted and a new comment added to the issue, pointing back to
-the original Git commit.
-
-RTC connectivity
------------------
-
-In order for Gerrit to connect to RTC REST-API, url and credentials
-are required in your gerrit.config / secure.config under the [its-rtc] section.
-
-**Example:**
-
- [its-rtc]
- url=https://rtc.gerritforge.com:9443/ccm
- username=rtcuser
- passsword=rtcpass
-
-RTC credentials and connectivity details are asked and verified during the Gerrit init.
-
-HTTP/S and network settings
----------------------------
-
-There are no additional settings required for a default connectivity from Gerrit
-to RTC and the default JVM settings are automatically taken for opening outbound
-connections.
-
-However connectivity to RTC could be highly customised for defining the protocol
-security level, pooling and network settings. This allows the administrator
-to have full control of the output pipe to RTC and the propagation of the Change events
-to the associated issues in a high-loaded production environment.
-
-All settings are defined in gerrit.config under the same [its-rtc] section.
-See below the list of the most important parameters and their associated meaning.
-
-`sslVerify`
-: `[TRUE|FALSE]`. When using HTTP/S to connect to RTC (the most typical scenario)
- allows to enforce (recommended) or disable (**ONLY FOR TEST ENVIRONMENTS**) the
- X.509 Certificates validation during SSL handshake. If unsure say TRUE.
-
-`httpSocketTimeout`
-: `<number>` Defines the socket timeout in milliseconds,
- which is the timeout for waiting for data or, put differently,
- a maximum period inactivity between two consecutive data packets).
- A timeout value of zero is interpreted as an infinite timeout.
-
-`httpSocketBufferSize`
-: `<number>` Determines the size of the internal socket buffer used to buffer data
- while receiving / transmitting HTTP messages.
-
-`httpSocketReuseaddr`
-: `[TRUE|FALSE]` Defines whether the socket can be bound even though a previous connection is
- still in a timeout state.
-
-`httpConnectionTimeout`
-: `<number>` Determines the timeout in milliseconds until a connection is established.
- A timeout value of zero is interpreted as an infinite timeout.
-
-`httpConnectionStalecheck`
-: `[TRUE|FALSE]` Determines whether stale connection check is to be used. The stale
- connection check can cause up to 30 millisecond overhead per request and
- should be used only when appropriate. For performance critical
- operations this check should be disabled.
-
-`httpSocketKeepalive`
-: `[TRUE|FALSE]` Defines whether or not TCP is to send automatically a keepalive probe to the peer
- after an interval of inactivity (no data exchanged in either direction) between this
- host and the peer. The purpose of this option is to detect if the peer host crashes.
-
-`httpConnManagerTimeout`
-: `<number>` Defines the timeout in milliseconds used when retrieving a free connection from the pool
- of outbound HTTP connections allocated.
-
-`httpConnManagerMaxTotal`
-: `<number>` Defines the maximum number of outbound HTTP connections in total.
- This limit is interpreted by client connection managers and applies to individual manager instances.
-
-**NOTE**: The full list of all available HTTP network connectivity parameters can be found under
-the [Apache Commons HTTP Client 4.2.x documentation](http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/index.html?org/apache/http/client/params/ClientPNames.html). Gerrit parameters names are the [CamelCase](http://en.wikipedia.org/wiki/Camelcase) version of the string
-values of the Apache HTTP Client ones.
-
-
-Gerrit init integration
------------------------
-
-RTC plugin is integrated as a Gerrit init step in order to simplify and guide
-through the configuration of RTC integration and connectivity check, avoiding
-bogus settings to prevent Gerrit plugin to start correctly.
-
-**Gerrit init example:**
-
- *** IBM Rational Team Concert Integration
- ***
-
- Issue tracker integration for all projects? [DISABLED/?]: enabled
- Branches for which the issue tracker integration should be enabled (ref, ref pattern or regular expression) [refs/heads/*]:
-
- *** IBM Rational Team Concert connectivity
- ***
-
- RTC CCM URL (empty to skip) : https://rtc.gerritforge.com:9443/ccm
- RTC username []: gerrit
- Change luca's password [y/N]? y
- luca's password : ******
- confirm password : ******
- Verify SSL Certificates [TRUE/?]: false
- Test connectivity to https://rtc.gerritforge.com:9443/ccm [y/N]: y
- Checking IBM Rational Team Concert connectivity ... [OK]
-
- *** Rational Team Concert issue-tracking association
- ***
-
- RTC issue-Id regex [RTC#([0-9]+)]:
- RTC-Id enforced in commit message [OPTIONAL/?]: suggested
-
-Issues workflow automation
---------------------------
-
-RTC plugin is able to automate status transition on the issues based on
-code-review actions performed on Gerrit; actions are performed on RTC using
-the username/password provided during Gerrit init.
-Transition automation is driven by `$GERRIT_SITE/issue-state-transition.config` file.
-
-Syntax of the status transition configuration file is the following:
-
- [action "<issue-status-action>"]
- change=<change-action>
- verified=<verified-value>
- code-review=<code-review-value>
-
-`<issue-status-action>`
-: Action to perform on RTC issue when all the condition in the stanza are met.
-
-`<change-action>`
-: Action performed on Gerrit change-id, possible values are:
- `created, commented, merged, abandoned, restored`
-
-`<verified-value>`
-: Verified flag added on Gerrit with values from -1 to +1
-
-`<code-review-value>`
-: Code-Review flag added on Gerrit with values from -2 to +2
-
-Note: multiple conditions in the action stanza are optional but at least one must be present.
-
-Example:
-
- [action "Start Progress"]
- change=created
-
- [action "Resolve Issue"]
- verified=+1
- code-review=+2
-
- [action "Close Issue"]
- change=merged
-
- [action "Stop Progress"]
- change=abandoned
-
-The above example defines four status transition on RTC, based on the following conditions:
-
-* Whenever a new Change-set is created on Gerrit, start progress on the RTC issue
-* Whenever a change is verified and reviewed with +2, transition the RTC issue to resolved
-* Whenever a change is merged to branch, mark the RTC transition the RTC issue to closed
-* Whenever a change is abandoned, stop the progress on RTC issue
