Merge pull request #3 from zanata/master

Combining the two builders and various fixes

.gitignore

@@ -0,0 +1,4 @@
+.idea/
+target/
+work/
+*.iml

Jenkinsfile

@@ -0,0 +1,4 @@
+#!/usr/bin/env groovy
+
+/* `buildPlugin` step provided by: https://github.com/jenkins-infra/pipeline-library */
+buildPlugin()

README.md

@@ -1,23 +1,98 @@
-# Zanata Plugin for Jenkins
+### A Jenkins plugin to synchronize localization resources between SCM repository and Zanata
 
-Yu Shao [email protected]
+Plugin home page: https://wiki.jenkins-ci.org/display/JENKINS/Zanata+Plugin
+
+[Zanata](https://zanata.org) is an open source translation management platform. 
 
-This plugin adds the zanata configuration into Jenkins.
+Once you install this jenkins plugin, you can set up a job to perform typical localization workflow:
+- check out from SCM
+- push source (and/or translation) to Zanata server for translators to work on
+- pull translation from Zanata server
+- commit translation into SCM (currently only git is supported automatically. Other SCM will need to use scripting)
+- push the commit to remote SCM (using git publisher or equivalent)
 
-Plugin home page: https://wiki.jenkins-ci.org/display/JENKINS/Zanata+Plugin
+### How to build and test locally
+In this project, if you have docker installed:
+
+```
+mvn clean package
+docker/runJenkins.sh
+```
+
+If you don't have docker:
+```
+hpiPluginRun.sh
+```
+
+### How to use it as normal Jenkins job
+First you will need to configure Zanata credentials in Jenkins Credentials view (plus e.g. github credential if you want to push commit).
+Then you will have two options to use Zanata client to push source to and/or pull translation from Zanata server.
+
+1. use the plugin as a build step
+    - in you job configuration, you can choose 'Zanata Sync' as a build step and fill in all the information in the UI
+
+2. install Zanata CLI on Jenkins node and use scripting to invoke it
+    - go to Jenkins global tools configuration view and there will be a Zanata CLI section for you to configure
+    - in your job configuration, you can choose to install the configured CLI under Build Environment section
+    - choose a shell builder step and run Zanata CLI from there
+
+Option 1 has the advantage of being installation free and simple to use. It will work on all type of jenkins slave nodes.
+It will commit translation after pull automatically if you use Git as SCM. 
+Disadvantage being that it uses only the included version of Zanata CLI java classes. and you can't do much customization for push and pull.
 
+Option 2 has the advantage of being flexible. You can use all the features and options of [Zanata CLI](http://zanata-client.readthedocs.io/en/release/).
+The disadvantage is, you will need to know how to use Zanata CLI. You also need to manually manage source control in your shell script.
 
-You need to install zanata client on the Jenkins server:
-http://docs.zanata.org/projects/zanata-client/en/release/
 
-- zanata.ini configuration
+### How to use it in pipeline build
+
+#### Use standard push and pull
+```groovy
+node {
+    // define common variables
+    def gitRepo = 'github.com/huangp/test-repo.git'
+    def gitBranch = 'trans'
+    def zanataCredentialsId = 'zanata'
+    def gitCredentialsId = 'huangp_github'
+    
+    
+    git([url: "https://$gitRepo", branch: gitBranch])
+    
+    // generated from Pipeline Syntax using general step
+    step([$class: 'ZanataSyncStep', pullFromZanata: true, pushToZanata: true, zanataCredentialsId: zanataCredentialsId, zanataProjectConfigs: '', zanataLocaleIds: ''])
+    
+    // copy from https://github.com/jenkinsci/pipeline-examples/blob/master/pipeline-examples/push-git-repo/pushGitRepo.Groovy
+    withCredentials([[$class: 'UsernamePasswordMultiBinding', credentialsId: gitCredentialsId, usernameVariable: 'GIT_USERNAME', passwordVariable: 'GIT_PASSWORD']]) {
+        sh('git push https://${GIT_USERNAME}:${GIT_PASSWORD}@' + ' ' + gitRepo)
+    }
+}
+
+```
+
+#### Install tool and run in shell 
+Assuming a Zanata CLI version 4.0.0 is pre-configured (it will generate a tool name 'zanata_cli_4_0_0').
+```groovy
+node {
+    // from Pipeline Syntax: select 'tool: Use a tool from a predefined Tool Installation' and then generate script
+    tool name: 'zanata_cli_4_0_0', type: 'org.jenkinsci.plugins.zanata.zanatareposync.ZanataCLIInstall'
+    
+    withEnv(["CLI_HOME=${ tool 'zanata_cli_4_0_0' }"]) {
+         sh '$CLI_HOME/bin/zanata-cli help'
+    }
+    
+}
+
+```
+
+### Alternative build step (experimental and subject to change without notice)
+
+Yu Shao [email protected]
 
-Find your zanata.ini information according to:
+Find your zanata credential information according to:
 http://docs.zanata.org/projects/zanata-client/en/release/configuration/
-Put the zanata.ini informtaion into Jenkins -> Manage Jenkins -> Configure System
 
-- Configure your build to include Zanata sync
+- Configure your build by selecting 'Zanata Sync via CLI' to use a pre-entered script template
 
-Configure Zanata Sync details, there are two sync actions in the plugin, one, pushing the English property file(s) to Zanata server defined in zanata.xml file in the source repo property directories.  Two, committing the finished Java property files from Zanata to the original Git repository. 
+Configure the sync details, there are two sync actions in the plugin, one, pushing the English source file(s) to Zanata server defined in zanata.xml file in the source repo property directories.  Two, committing the finished translation files from Zanata to the original Git repository. 
 
 Both two types of sync are running the default shell scripts, you could customize the shell scripts, you could customize the two sync actions according to your build need by enabling or disabling them

docker/Dockerfile

@@ -0,0 +1,28 @@
+FROM jenkins:2.32.2
+
+
+# COPY plugins.txt /usr/share/jenkins/plugins.txt
+
+# plugins.sh takes an explicit list of plugins and their dependencies from a file. It can not resolve dependencies
+# install-plugins.sh will resolve dependencies but only install the version listed in the plugin
+# RUN /usr/local/bin/plugins.sh /usr/share/jenkins/plugins.txt
+
+
+ENV INIT_PLUGINS="git maven-plugin mailer credentials credentials-binding parameterized-trigger" DEBUG_PORT=8989
+
+# copy our own utility scripts. To avoid overriding jenkins provide scripts, we prefix our scripts with z_
+COPY scripts/ /usr/local/bin/
+COPY zanata.hpi ${JENKINS_HOME}/plugins/
+
+USER root
+RUN chmod go+x /usr/local/bin/z_*
+
+USER ${user}
+
+#ENV JAVA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,address=$DEBUG_PORT,server=y,suspend=n"
+
+RUN /usr/local/bin/z_install_plugins.sh ${INIT_PLUGINS}
+
+
+
+

docker/build.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+# determine directory containing this script
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
+  DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE" # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
+
+PLUGIN=$(ls $DIR/../target/*.hpi)
+
+if [ -f "$PLUGIN" ]
+then
+    # we have to link the file here so that docker build can copy the file into the image
+    ln ${PLUGIN} ${DIR}/zanata.hpi
+else
+    echo please build the plugin first
+    exit 1
+fi
+
+docker build -t zjenkins/dev ${DIR}
+
+# clean up the file (only needed for docker build)
+rm ${DIR}/zanata.hpi
+

docker/runJenkins.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# determine directory containing this script
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve $SOURCE until the file is no longer a symlink
+  DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE" # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" && pwd )"
+
+${DIR}/build.sh
+
+docker run -p 8080:8080 -p 50000:50000 -p 8989:8989 --name zjen zjenkins/dev

docker/scripts/z_install_plugins.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# usage: $BASH_SOURCE[0] pluginA[:version] pluginB 
+for plugin in $@; do
+    # set the internal field separator (IFS) variable, and then let it parse into an array.
+    # When this happens in a command, then the assignment to IFS only takes place to that single command's environment (to read ).
+    # It then parses the input according to the IFS variable value into an array
+    IFS=':' read -ra pluginVer <<< "$plugin"
+    if [ ${#pluginVer[@]} -eq 2 ]
+    then
+        install-plugins.sh $pluginVer[0] $pluginVer[1]
+    else
+	install-plugins.sh $plugin
+    fi
+done
+

docker/scripts/z_restart.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+java -jar ${JENKINS_HOME}/war/WEB-INF/jenkins-cli.jar -s http://localhost:8080/ restart
+

docker/scripts/z_update-index.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# -q quiet -O output to file (- means stdin)
+# sed '1d;$d' means remove first and last line
+wget http://updates.jenkins-ci.org/update-center.json -qO- | sed '1d;$d'  > ${JENKINS_HOME}/updates/default.json
+

hpiPluginRun.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -x
+
+CMD='mvn'
+while getopts ":dH" opt; do
+  case ${opt} in
+    d)
+      CMD='mvnDebug'
+      echo 'will run mvnDebug'
+      ;;
+    H)
+      echo "========   HELP   ========="
+      echo "-d  : run mavenDebug instead"
+      echo "-h  : display help"
+      exit
+      ;;
+    \?)
+      echo "Invalid option: -${OPTARG}. Use -h for help" >&2
+      exit 1
+      ;;
+  esac
+done
+${CMD} org.jenkins-ci.tools:maven-hpi-plugin:run