Skip to content

Commit 8500895

Browse files
trivaliktrivalik
authored
Merge branch 'master' into trivalik-patch-1
2 parents 99034d3 + aea4ce0 commit 8500895

File tree

524 files changed

+15321
-1626
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

524 files changed

+15321
-1626
lines changed

‎.gitignore

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
/.settings
2-
/target
3-
/workspaces
4-
/work
5-
/.project
6-
/.classpath
1+
.settings
2+
**/target
3+
**/workspaces
4+
**/work
5+
.project
6+
.classpath
77
/.idea
8-
/*.iml
8+
**/*.iml

‎Jenkinsfile

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
pipeline {
2+
agent any
3+
stages {
4+
stage('Build') {
5+
steps {
6+
buildPlugin()
7+
}
8+
}
9+
}
10+
}

‎README.md

+242-62
Large diffs are not rendered by default.

‎ReleaseNotes.md

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
These notes are for release **(to be determined)**.
2+
Other releases and their notes can be found at the [tfs-plugin GitHub Releases](https://github.com/jenkinsci/tfs-plugin/releases) page.
3+
4+
* Major:
5+
* TODO
6+
7+
* Minor:
8+
* TODO
9+

‎Releasing.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
Pre-requisites
2+
==============
3+
4+
1. Machine: preferably Linux over Windows, to avoid any weirdness between Cygwin and Git for Windows
5+
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)
6+
1. Maven 3.2 or better
7+
1. A recent enough Git
8+
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.
9+
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)
10+
1. A "Jenkins infrastructure" account. They have some sort of LDAP server that provides SSO for JIRA, Confluence and Artifactory.
11+
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:
12+
```xml
13+
<?xml version="1.0" encoding="UTF-8"?>
14+
<settings
15+
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
16+
xmlns="http://maven.apache.org/SETTINGS/1.1.0"
17+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
18+
<servers>
19+
<server>
20+
<id>repo.jenkins-ci.org</id>
21+
<username>TODO</username>
22+
<password>TODO</password>
23+
</server>
24+
</servers>
25+
</settings>
26+
```
27+
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.
28+
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.
29+
1. A TFS server or a Azure DevOps account, configured as per `Testing.md`
30+
31+
Release
32+
=======
33+
34+
1. Pre-release. Perform these manual steps on your workstation:
35+
1. Run a full build, with all its end-to-end tests; it takes about 5 minutes:
36+
```
37+
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>
38+
```
39+
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.
40+
3. Fill in the categories of the `ReleaseNotes.md` template, usually in one of the following formats:
41+
1. &lt;Summary>. Thanks to @&lt;GitHub user name> for pull request #&lt;pull request number>.
42+
2. &lt;Summary>, via pull request #&lt;pull request number>.
43+
4. Decide on the release version and on the next development version, based on the rules of [Semantic Versioning](http://semver.org/).
44+
5. Update `ReleaseNotes.md` with the release version and merge/push to `master`.
45+
6. Merge any "wiki" changes to `master`.
46+
2. Automated release. Create a Jenkins job as follows:
47+
1. General
48+
1. Check "This project is parameterised"
49+
1. String parameter **releaseVersion**
50+
2. String parameter **developmentVersion**
51+
2. SCM
52+
1. Git
53+
1. Repository Url: **[email protected]:jenkinsci/tfs-plugin.git**
54+
2. Credentials: (select your previously-entered private key file)
55+
3. Name: **origin**
56+
4. Refspec: **+refs/heads/master:refs/remotes/origin/master**
57+
5. Branch Specifier: **refs/heads/master**
58+
6. Repository browser: **githubweb**
59+
7. Additional Behaviours:
60+
1. Clean before checkout
61+
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/))
62+
1. Branch name: **master**
63+
3. Build Environment
64+
1. Add timestamps to the Console Output
65+
2. Inject environment variables to the build process
66+
1. **COMPUTERNAME** (the host name of the Jenkins node that will run the job)
67+
2. **TFS_SERVER_NAME** (the TFS host name or Azure DevOps account host name)
68+
3. Use secret text(s) or file(s)
69+
1. **TFS_USER_NAME** and **TFS_USER_PASSWORD** are initialized from a credential
70+
4. Build. Add the following steps:
71+
1. "Shell script" step to check and prepare (filling in the blanks at the `git config` lines near the end)
72+
```bash
73+
set +e
74+
75+
# verify releaseVersion and developmentVersion
76+
if [[ "$releaseVersion" != +([0-9])\.+([0-9])\.+([0-9]) ]]
77+
then
78+
echo "ERROR: '$releaseVersion' is not a valid releaseVersion"
79+
exit 1
80+
fi
81+
82+
if [[ "$developmentVersion" != +([0-9])\.+([0-9])\.+([0-9])-SNAPSHOT ]]
83+
then
84+
echo "ERROR: '$developmentVersion' is not a valid developmentVersion"
85+
exit 1
86+
fi
87+
88+
89+
# test SSH connection to Git
90+
ssh -Tv [email protected]
91+
if [[ $? != "1" ]]
92+
then
93+
echo "ERROR: Unable to connect to GitHub via SSH"
94+
exit 1
95+
fi
96+
97+
git config --local user.name '<your full name>'
98+
git config --local user.email '<your e-mail address>'
99+
100+
exit 0
101+
```
102+
2. "Maven" step as a dry-run, running all tests and performing a SNAPSHOT deploy
103+
```
104+
deploy
105+
dependency:go-offline
106+
--batch-mode
107+
-Dtfs_server_name=${TFS_SERVER_NAME}
108+
-Dtfs_user_name=${TFS_USER_NAME}
109+
-Dtfs_user_password=${TFS_USER_PASSWORD}
110+
```
111+
3. "Maven" step to actually release
112+
```
113+
clean
114+
release:prepare
115+
release:perform
116+
--batch-mode
117+
-Dtag=tfs-${releaseVersion}
118+
-DreleaseVersion=${releaseVersion}
119+
-DdevelopmentVersion=${developmentVersion}
120+
```
121+
4. "Shell script" step for post-release actions (filling in the blanks at the `git config` lines near the beginning)
122+
```bash
123+
cd target/checkout
124+
git config --local user.name '<your full name>'
125+
git config --local user.email '<your e-mail address>'
126+
 
127+
git checkout -b update_documentation_for_$releaseVersion origin/master
128+
 
129+
cat > ReleaseNotes.md <<EndOfReleaseNotes
130+
These notes are for release **(to be determined)**.
131+
Other releases and their notes can be found at the [tfs-plugin GitHub Releases](https://github.com/jenkinsci/tfs-plugin/releases) page.
132+
 
133+
* Major:
134+
* TODO
135+
* Minor:
136+
* TODO
137+
 
138+
EndOfReleaseNotes
139+
git commit -a -m "Clear out the release notes for the next release"
140+
 
141+
git push origin update_documentation_for_$releaseVersion
142+
```
143+
5. Files to archive:
144+
```
145+
tfs/target/tfs.hpi,ReleaseNotes.md,README.md,images/**
146+
```
147+
3. Post-release. Perform these manual steps on your workstation:
148+
1. Download the artifacts from Jenkins
149+
2. Create a pull request from the **update_documentation_for_$releaseVersion** branch, then merge it.
150+
3. Edit the tag on GitHub:
151+
1. Copy-paste most of `ReleaseNotes.md`.
152+
2. Upload the artifacts downloaded from Jenkins.
153+
3. Publish release.
154+
4. Update `README.md`.
155+
5. Update affected issues with "Fixed in".
156+
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

+18-14
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,12 @@
11
Functional Tests
22
================
3-
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.
3+
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.
44

55
How to configure your TFS server
66
--------------------------------
77
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).
88

9-
1. Add a **jenkins-tfs-plugin** user to the domain.
10-
1. Set its password to **for-test-only**, with no password expiry. (you may need to temporarily disable the
11-
*Password must meet complexity requirements* policy, under Computer Configuration > Policies > Windows Settings > Security Settings > Account Policies > Password Policy)
12-
2. Launch the **Team Foundation Server Administration Console**
9+
1. Launch the **Team Foundation Server Administration Console**
1310
1. Navigate to root > Application Tier > Team Project Collections
1411
2. Click **Create Collection**
1512
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
1815
6. Assuming everything was fine, click **Create**
1916
7. Wait about 1 minute for the process to complete.
2017
8. Assuming the team project collection was created OK, click **Close**
21-
3. Follow the instructions at [Create a team project](https://msdn.microsoft.com/library/ms181477.aspx) to create a *Team Project*, as specified below:
18+
2. Follow the instructions at [Create a team project](https://msdn.microsoft.com/library/ms181477.aspx) to create a *Team Project*, as specified below:
2219
1. When prompted for the *Name*, enter **FunctionalTests**
2320
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.
2421
3. The choice of process template is not important.
2522
4. Select **Team Foundation Version Control** as the *version control system*.
26-
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
27-
5. Test it!
23+
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
24+
5. Ensure the user has access to the team project
2825
1. Open a web browser in InPrivate/incognito/private mode. This will make sure you aren't re-using authentication cookies or saved credentials.
2926
2. Navigate to the **jenkins-tfs-plugin** team project collection on the server. Example: `http://tfs.corp.example.com:8080/tfs/jenkins-tfs-plugin`
30-
3. Log in as **jenkins-tfs-plugin** with password **for-test-only**
27+
3. Log in as the test user.
3128
4. Confirm you can browse to the **FunctionalTests** team project.
3229

3330

34-
How to configure your VSO account
35-
---------------------------------
36-
TODO: write this when Visual Studio Online is supported.
31+
How to configure your Azure DevOps account
32+
-------------------------------------------
33+
TODO: write this
3734

3835

3936
How to configure your development environment
4037
---------------------------------------------
41-
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.
38+
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.
39+
You should also provide the following properties:
40+
41+
1. tfs_server_name - set this to the host name of the server (ex. tfs.corp.example.com)
42+
2. tfs_collection_url - set this to the full url of the collection (ex. http://tfs.corp.example.com:8081/tfs/jenkins-tfs-plugin)
43+
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**)
44+
4. tfs_user_password - set this to the password of the test user (the default value if not provided is **for-test-only**)
45+
5. Set the COMPUTERNAME environment variable as the end-to-end tests rely on its presence
4246

4347
Example:
4448

45-
mvn clean verify -Dtfs_server_name=tfs.corp.example.com
49+
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
4650

‎contributing.md

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
Contributing to the Team Foundation Server plugin for Jenkins
2+
=============================================================
3+
4+
## Building Sources
5+
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.
6+
- SET JAVA_HOME to the location of the JRE to build with (JRE 1.8 works)
7+
- Clone the repo from https://github.com/jenkinsci/tfs-plugin.git
8+
- change dir to the tfs-plugin folder
9+
- run "mvn package"
10+
- 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.
11+
- Initial build will have to download lots of libraries. This could take a few minutes.
12+
- This produces tfs-plugin\tfs\target\tfs.hpi
13+
14+
## Using IntelliJ IDEA
15+
To use Intellij IDEA as the editor for this project simply do the following after getting sources:
16+
1) Open the tfs-plugin folder (root folder) in IntelliJ (I installed IntelliJ 17 community edition from https://www.jetbrains.com/idea/)
17+
2) Go to File->Project Structure and click on Project
18+
3) Specify the Project SDK (Java 1.8 works)
19+
20+
You should now be able to build from within IntelliJ
21+
- NOTE to build the hpi file you will have to
22+
- bring up the Maven Projects tool window (View->Tool Windows->Maven Projects) and click the "execute maven goal" button
23+
- Then type "package" in the "Command Line" text box (of the Execute Maven Goal dialog)
24+
25+
## Debugging the Plugin
26+
See https://wiki.jenkins-ci.org/display/JENKINS/Plugin+tutorial for information on how to debug the plugin.
27+
From within IntelliJ:
28+
1) Create a new Run configuration (Run | Edit Configurations... | + )
29+
1) Type = Maven
30+
1) Name = run hpi
31+
1) Working directory should be the full path to "../tfs-plugin/tfs" (NOTE this is NOT the root folder)
32+
1) Command Line
33+
34+
`
35+
hpi:run -Djetty.port=8090 -Dhudson.plugins.tfs.telemetry.isDeveloperMode=true
36+
`
37+
38+
1) or use whatever port you want
39+
1) On the Runner tab
40+
1) Environment Variables == MAVEN_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n
41+
1) To set the environment variables, make sure you uncheck 'Use project settings' first. Then use the '...' to set the variable.
42+
43+
1) Run or Debug this configuration using the play and debug icons (top right)
44+
1) Set any breakpoints you want in IntelliJ
45+
1) Navigate to http://localhost:8090/jenkins
46+
47+
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).
48+
49+
## Installing Jenkins Locally for Manual Testing
50+
The easiest method is to run Jenkins in a Docker image.
51+
1) Install Docker for your OS (https://www.docker.com/community-edition)
52+
1) Install and run the Jenkins image
53+
54+
`
55+
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
56+
`
57+
58+
- NOTES:
59+
- Note that this command line avoids port 8080 (the default) in case you have VSO deployed as well
60+
- Look in the output for the admin password
61+
- The output sent to the console is also where you will see any logger output
62+
- 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
63+
- This installs a Linux Jenkins server on Docker (NOT one based on Windows or the host OS)
64+
1) Setup Jenkins
65+
1) Go to http://localhost:9191
66+
1) Enter the admin password
67+
1) Install default plugins
68+
1) Run Jenkins
69+
1) Install Plugin Manually
70+
1) Go to http://localhost:9191/pluginManager/advanced
71+
1) Browse to the tfs.hpi file and Upload it
72+
1) To update the plugin, repeat steps 1 and 2 and then restart Jenkins by going to http://localhost:9191/restart
73+
1) To stop Jenkins and start from scratch
74+
75+
`
76+
docker stop localJenkins
77+
docker container prune
78+
`
79+
80+
Then repeat step 2 and 3 above

‎git-job-config.png

18.3 KB
Loading

‎images/AutomaticIntegration.png

32.5 KB
Loading

‎images/addPostBuildAction.png

18.4 KB
Loading

‎images/fillFieldsForPostBuildAction.JPG

61.3 KB
Loading

‎images/git-job-config.png

18.3 KB
Loading

‎images/rmWithJenkins-YT.png

91.5 KB
Loading

‎images/tfs-job-config4.png

20.8 KB
Loading

0 commit comments

Comments
 (0)