Merge branch 'master' into trivalik-patch-1

.gitignore

@@ -1,8 +1,8 @@
-/.settings
-/target
-/workspaces
-/work
-/.project
-/.classpath
+.settings
+**/target
+**/workspaces
+**/work
+.project
+.classpath
 /.idea
-/*.iml
+**/*.iml

Jenkinsfile

@@ -0,0 +1,10 @@
+pipeline {
+    agent any
+    stages {
+        stage('Build') {
+            steps {
+                buildPlugin()
+            }
+        }
+    }
+}

ReleaseNotes.md

@@ -0,0 +1,9 @@
+These notes are for release **(to be determined)**.
+Other releases and their notes can be found at the [tfs-plugin GitHub Releases](https://github.com/jenkinsci/tfs-plugin/releases) page.
+
+* Major:
+    * TODO
+
+* Minor:
+    * TODO
+

Releasing.md

@@ -0,0 +1,156 @@
+Pre-requisites
+==============
+
+1. Machine: preferably Linux over Windows, to avoid any weirdness between Cygwin and Git for Windows
+    1. Oracle JDK 8 (see note in [Installing Jenkins on Red Hat distributions](https://wiki.jenkins-ci.org/display/JENKINS/Installing+Jenkins+on+Red+Hat+distributions) about CentOS's default Java)
+    1. Maven 3.2 or better
+    1. A recent enough Git
+    1. Make sure the `COMPUTERNAME` environment variable is defined, as the end-to-end tests rely on its presence.  One can use the [EnvInject plugin](https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin) to set it during the execution of the release job.
+1. A GitHub clone you can pull from and push to non-interactively. (Consider configuring GitHub with a public key and use the SSH protocol for everything)
+1. A "Jenkins infrastructure" account.  They have some sort of LDAP server that provides SSO for JIRA, Confluence and Artifactory.
+    1. If you can log in to https://repo.jenkins-ci.org with your account, you're set to punch in those credentials in your `~/.m2/settings.xml` file:
+    ```xml
+    <?xml version="1.0" encoding="UTF-8"?>
+    <settings
+      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" 
+      xmlns="http://maven.apache.org/SETTINGS/1.1.0"
+      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+      <servers>
+        <server>
+          <id>repo.jenkins-ci.org</id>
+          <username>TODO</username>
+          <password>TODO</password>
+        </server>
+      </servers>
+    </settings>
+    ```
+    2. A great test is to try to perform a `mvn deploy`, which should attempt to upload some files to the snapshot repo and will need those credentials.
+	3. If you're worried about putting your "Jenkins infrastructure" password  in plain-text in that file, Maven has a password encryption facility that relies on a master password in another file.  Presumably, you secure access to the 2nd file by placing it on a thumbdrive that you carry with you when you're not at your computer, etc.
+1. A TFS server or a Azure DevOps account, configured as per `Testing.md`
+
+Release
+=======
+
+1. Pre-release.  Perform these manual steps on your workstation:
+    1. Run a full build, with all its end-to-end tests; it takes about 5 minutes:
+    ```
+    mvn clean verify --batch-mode -Dtfs_server_name=&lt;TFS host name or Azure DevOps account host name> -Dtfs_user_name=&lt;user> -Dtfs_user_password=&lt;password>
+    ```
+    2. Look at the commits since the last release by going to https://github.com/jenkinsci/tfs-plugin/releases and clicking the "XX commits to master since this release" link.  It will be easiest to surf the associated pull requests, so hit Ctrl+F, search for "Merge pull request" and Ctrl+click every #XXX link to the right of the highlights.
+    3. Fill in the categories of the `ReleaseNotes.md` template, usually in one of the following formats:
+        1. &lt;Summary>. Thanks to @&lt;GitHub user name> for pull request #&lt;pull request number>.
+        2. &lt;Summary>, via pull request #&lt;pull request number>.
+    4. Decide on the release version and on the next development version, based on the rules of [Semantic Versioning](http://semver.org/).
+    5. Update `ReleaseNotes.md` with the release version and merge/push to `master`.
+    6. Merge any "wiki" changes to `master`.
+2. Automated release.  Create a Jenkins job as follows:
+    1. General
+        1. Check "This project is parameterised"
+            1. String parameter **releaseVersion**
+            2. String parameter **developmentVersion**
+    2. SCM
+        1. Git
+            1. Repository Url: **[email protected]:jenkinsci/tfs-plugin.git**
+            2. Credentials: (select your previously-entered private key file)
+            3. Name: **origin**
+            4. Refspec: **+refs/heads/master:refs/remotes/origin/master**
+			5. Branch Specifier: **refs/heads/master**
+			6. Repository browser: **githubweb**
+			7. Additional Behaviours:
+			    1. Clean before checkout
+				2. Check out to specific local branch (to avoid ["Git fatal: ref HEAD is not a symbolic ref" while using maven release plugin](https://stackoverflow.com/a/21184154/))
+					1. Branch name: **master**
+    3. Build Environment
+		1. Add timestamps to the Console Output
+		2. Inject environment variables to the build process
+		    1. **COMPUTERNAME** (the host name of the Jenkins node that will run the job)
+            2. **TFS_SERVER_NAME** (the TFS host name or Azure DevOps account host name)
+        3. Use secret text(s) or file(s)
+			1. **TFS_USER_NAME** and **TFS_USER_PASSWORD** are initialized from a credential
+    4. Build. Add the following steps:
+        1. "Shell script" step to check and prepare (filling in the blanks at the `git config` lines near the end)
+        ```bash
+        set +e
+
+        # verify releaseVersion and developmentVersion
+        if [[ "$releaseVersion" != +([0-9])\.+([0-9])\.+([0-9]) ]]
+        then
+            echo "ERROR: '$releaseVersion' is not a valid releaseVersion"
+            exit 1
+        fi
+
+        if [[ "$developmentVersion" != +([0-9])\.+([0-9])\.+([0-9])-SNAPSHOT ]]
+        then
+            echo "ERROR: '$developmentVersion' is not a valid developmentVersion"
+            exit 1
+        fi
+
+
+        # test SSH connection to Git
+        ssh -Tv [email protected]
+        if [[ $? != "1" ]]
+        then
+            echo "ERROR: Unable to connect to GitHub via SSH"
+            exit 1
+        fi
+
+        git config --local user.name '<your full name>'
+        git config --local user.email '<your e-mail address>'
+
+        exit 0
+        ```
+        2. "Maven" step as a dry-run, running all tests and performing a SNAPSHOT deploy
+        ```
+        deploy
+        dependency:go-offline
+        --batch-mode
+        -Dtfs_server_name=${TFS_SERVER_NAME}
+        -Dtfs_user_name=${TFS_USER_NAME}
+        -Dtfs_user_password=${TFS_USER_PASSWORD}
+        ```
+        3. "Maven" step to actually release
+        ```
+        clean
+        release:prepare
+        release:perform
+        --batch-mode
+        -Dtag=tfs-${releaseVersion}
+        -DreleaseVersion=${releaseVersion}
+        -DdevelopmentVersion=${developmentVersion}
+        ```
+        4. "Shell script" step for post-release actions (filling in the blanks at the `git config` lines near the beginning)
+        ```bash
+        cd target/checkout
+        git config --local user.name '<your full name>'
+        git config --local user.email '<your e-mail address>'
+
+        git checkout -b update_documentation_for_$releaseVersion origin/master
+
+        cat > ReleaseNotes.md <<EndOfReleaseNotes
+        These notes are for release **(to be determined)**.
+        Other releases and their notes can be found at the [tfs-plugin GitHub Releases](https://github.com/jenkinsci/tfs-plugin/releases) page.
+
+        * Major:
+            * TODO
+        * Minor:
+            * TODO
+
+        EndOfReleaseNotes
+        git commit -a -m "Clear out the release notes for the next release"
+
+        git push origin update_documentation_for_$releaseVersion
+        ```
+        5. Files to archive:
+        ```
+        tfs/target/tfs.hpi,ReleaseNotes.md,README.md,images/**
+        ```
+3. Post-release.  Perform these manual steps on your workstation:
+    1. Download the artifacts from Jenkins
+    2. Create a pull request from the **update_documentation_for_$releaseVersion** branch, then merge it.
+    3. Edit the tag on GitHub:
+        1. Copy-paste most of `ReleaseNotes.md`.
+        2. Upload the artifacts downloaded from Jenkins.
+        3. Publish release.
+    4. Update `README.md`.
+    5. Update affected issues with "Fixed in".
+    6. Check the update mirror after about a day, to make sure the new version was replicated across the CDN: http://updates.jenkins-ci.org/update-center.json

Testing.md

@@ -1,15 +1,12 @@
 Functional Tests
 ================
-There's only so much testing you can do with test friends such as mocks and network replayers.  To enable more comprehensive and realistic testing, some automated tests were written to talk to live TFS servers.  Some manual, one-time set-up is required to facilitate the process.
+There's only so much testing you can do with test friends such as mocks and network replayers.  To enable more comprehensive and realistic testing, some automated tests were written to talk to live servers.  Some manual, one-time set-up is required to facilitate the process.
 
 How to configure your TFS server
 --------------------------------
 You'll need to be (or involve) an administrator.  It is assumed your TFS server is installed at the default port (8080) and virtual directory (/tfs).
 
-1. Add a **jenkins-tfs-plugin** user to the domain.
-    1. Set its password to **for-test-only**, with no password expiry. (you may need to temporarily disable the 
-*Password must meet complexity requirements* policy, under Computer Configuration > Policies > Windows Settings > Security Settings > Account Policies > Password Policy)
-2. Launch the **Team Foundation Server Administration Console**
+1. Launch the **Team Foundation Server Administration Console**
     1. Navigate to root > Application Tier > Team Project Collections
     2. Click **Create Collection**
     3. Set the *Name* to **jenkins-tfs-plugin**
@@ -18,29 +15,36 @@ You'll need to be (or involve) an administrator.  It is assumed your TFS server
     6. Assuming everything was fine, click **Create**
     7. Wait about 1 minute for the process to complete.
     8. Assuming the team project collection was created OK, click **Close**
-3. Follow the instructions at [Create a team project](https://msdn.microsoft.com/library/ms181477.aspx) to create a *Team Project*, as specified below:
+2. Follow the instructions at [Create a team project](https://msdn.microsoft.com/library/ms181477.aspx) to create a *Team Project*, as specified below:
     1. When prompted for the *Name*, enter **FunctionalTests**
     2. Indicate in the *Description* field that this team project was created for the automated functional tests.  A hyperlink to this page would probably be a good idea.
     3. The choice of process template is not important.
     4. Select **Team Foundation Version Control** as the *version control system*.
-4. Follow the instructions at [Add team members](https://msdn.microsoft.com/en-us/library/jj920206.aspx) to add the **jenkins-tfs-plugin** user as a member of the **FunctionalTests** team project
-5. Test it!
+4. Follow the instructions at [Add team members](https://msdn.microsoft.com/en-us/library/jj920206.aspx) to add the test user as a member of the **FunctionalTests** team project
+5. Ensure the user has access to the team project
     1. Open a web browser in InPrivate/incognito/private mode.  This will make sure you aren't re-using authentication cookies or saved credentials.
     2. Navigate to the **jenkins-tfs-plugin** team project collection on the server.  Example:  `http://tfs.corp.example.com:8080/tfs/jenkins-tfs-plugin`
-    3. Log in as **jenkins-tfs-plugin** with password **for-test-only**
+    3. Log in as the test user.
     4. Confirm you can browse to the **FunctionalTests** team project.
 
 
-How to configure your VSO account
----------------------------------
-TODO: write this when Visual Studio Online is supported.
+How to configure your Azure DevOps account
+-------------------------------------------
+TODO: write this
 
 
 How to configure your development environment
 ---------------------------------------------
-Tests that need to connect to a TFS server will only run during the `verify` phase *if* the `tfs_server_name` property was provided to Maven.  The value of this property is the *fully-qualified DNS name (FQDN)* of the TFS server, because a non-qualified host name appears to trigger NTLM authentication attempts.
+Tests that need to connect to a server will only run during the `verify` phase *if* the `tfs_server_name` property was provided to Maven.  The value of this property is the *fully-qualified DNS name (FQDN)* of the server, because a non-qualified host name appears to trigger NTLM authentication attempts.
+You should also provide the following properties:
+
+1. tfs_server_name - set this to the host name of the server (ex. tfs.corp.example.com)
+2. tfs_collection_url - set this to the full url of the collection (ex. http://tfs.corp.example.com:8081/tfs/jenkins-tfs-plugin)
+3. tfs_user_name - set this to the test user you gave permissions to above (the default value if not provided is **jenkins-tfs-plugin**)
+4. tfs_user_password - set this to the password of the test user (the default value if not provided is **for-test-only**)
+5. Set the COMPUTERNAME environment variable as the end-to-end tests rely on its presence
 
 Example:
 
-    mvn clean verify -Dtfs_server_name=tfs.corp.example.com
+    mvn clean verify -Dtfs_collection_url="http://tfs.corp.example.com:8081/tfs/jenkins-tfs-plugin" -Dtfs_server_name=tfs.corp.example.com -Dtfs_user_name=jenkins-tfs-plugin -Dtfs_user_password=for-test-only
 

contributing.md

@@ -0,0 +1,80 @@
+Contributing to the Team Foundation Server plugin for Jenkins
+=============================================================
+
+## Building Sources
+This is a Maven project with Java sources. The mvn package command will produce an HPI file that is the Jenkins Plugin file that will need to be installed on your Jenkins Server.
+- SET JAVA_HOME to the location of the JRE to build with (JRE 1.8 works)
+- Clone the repo from https://github.com/jenkinsci/tfs-plugin.git
+- change dir to the tfs-plugin folder
+- run "mvn package"
+    - If you do not have Maven installed yet, here are [instructions](http://www.mkyong.com/maven/how-to-install-maven-in-windows/) on how to install it on Windows.
+    - Initial build will have to download lots of libraries. This could take a few minutes.
+- This produces tfs-plugin\tfs\target\tfs.hpi
+
+## Using IntelliJ IDEA
+To use Intellij IDEA as the editor for this project simply do the following after getting sources:
+1) Open the tfs-plugin folder (root folder) in IntelliJ (I installed IntelliJ 17 community edition from https://www.jetbrains.com/idea/)
+2) Go to File->Project Structure and click on Project
+3) Specify the Project SDK (Java 1.8 works)
+
+You should now be able to build from within IntelliJ
+- NOTE to build the hpi file you will have to 
+    - bring up the Maven Projects tool window (View->Tool Windows->Maven Projects) and click the "execute maven goal" button
+    - Then type "package" in the "Command Line" text box (of the Execute Maven Goal dialog)
+
+## Debugging the Plugin
+See https://wiki.jenkins-ci.org/display/JENKINS/Plugin+tutorial for information on how to debug the plugin.
+From within IntelliJ:
+1) Create a new Run configuration (Run | Edit Configurations... | + )
+    1) Type = Maven
+    1) Name = run hpi
+    1) Working directory should be the full path to "../tfs-plugin/tfs" (NOTE this is NOT the root folder)
+    1) Command Line 
+
+        `
+        hpi:run -Djetty.port=8090 -Dhudson.plugins.tfs.telemetry.isDeveloperMode=true
+        `
+
+        1) or use whatever port you want
+    1) On the Runner tab
+        1) Environment Variables == MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n
+        1) To set the environment variables, make sure you uncheck 'Use project settings' first. Then use the '...' to set the variable.
+
+1) Run or Debug this configuration using the play and debug icons (top right)
+    1) Set any breakpoints you want in IntelliJ
+    1) Navigate to http://localhost:8090/jenkins
+
+Note: this runs Jenkins on your local OS not in a Docker image. As such, any configurations you make are preserved between runs. You do not need to have Jenkins previously installed locally (IntelliJ will run Jenkins from a local JAR file).
+
+## Installing Jenkins Locally for Manual Testing
+The easiest method is to run Jenkins in a Docker image.
+1) Install Docker for your OS (https://www.docker.com/community-edition)
+1) Install and run the Jenkins image
+
+    `
+    docker run --name localJenkins -p 9191:9191 -p 50001:50001 --env "JENKINS_OPTS=--httpPort=9191" --env JENKINS_SLAVE_AGENT_PORT=50001 --env hudson.plugins.tfs.telemetry.isDeveloperMode=true jenkins
+    `
+
+    - NOTES: 
+        - Note that this command line avoids port 8080 (the default) in case you have VSO deployed as well
+        - Look in the output for the admin password
+        - The output sent to the console is also where you will see any logger output
+        - Note the environment variable "hudson.plugins.tfs.telemetry.isDeveloperMode". It is important to set this variable so that AppInsights data is sent to right key
+        - This installs a Linux Jenkins server on Docker (NOT one based on Windows or the host OS)
+1) Setup Jenkins
+    1) Go to http://localhost:9191
+    1) Enter the admin password
+    1) Install default plugins
+    1) Run Jenkins
+1) Install Plugin Manually
+    1) Go to http://localhost:9191/pluginManager/advanced
+    1) Browse to the tfs.hpi file and Upload it
+    1) To update the plugin, repeat steps 1 and 2 and then restart Jenkins by going to http://localhost:9191/restart
+1) To stop Jenkins and start from scratch
+
+    `
+    docker stop localJenkins
+    docker container prune
+    `
+
+    Then repeat step 2 and 3 above