diff --git a/Releasing.md b/Releasing.md new file mode 100644 index 000000000..803fe2241 --- /dev/null +++ b/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 + + + + + repo.jenkins-ci.org + TODO + TODO + + + + ``` + 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 VSTS 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=<TFS host name or VSTS account host name> -Dtfs_user_name=<user> -Dtfs_user_password=<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. <Summary>. Thanks to @<GitHub user name> for pull request #<pull request number>. + 2. <Summary>, via pull request #<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: **git@github.com: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 VSTS 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 git@github.com + if [[ $? != "1" ]] + then + echo "ERROR: Unable to connect to GitHub via SSH" + exit 1 + fi + + git config --local user.name '' + git config --local user.email '' + + 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 '' + git config --local user.email '' +   + git checkout -b update_documentation_for_$releaseVersion origin/master +   + cat > ReleaseNotes.md <