//  ========================================================================
//  Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[releasing-jetty]]
=== Releasing Jetty

There are a number of steps to releasing jetty.
It is not just limited to running a couple of maven commands and then moving onto bigger and better things.
There are a number of process related issues once the fun maven bits have been completed.

[[releasing-process]]
==== Building and Staging a Releasable Version

This release script is for jetty-9 (to release jetty-7 or jetty-8 see older documentation).

1.  Pick your version identification strings.
+
These follow a strict format and will be used when prompted during step link:#prepare-release-step[listitem_title] below.
+
....

Release Version                : 9.0.0.v20130322  (v[year][month][day])
Next Development Version       : 9.0.1-SNAPSHOT
Tag Name                       : jetty-9.9.0.v20130322

        
....
2.  We use the 'release-9' branch to avoid problems with other developers actively working on the master branch.
+
[source, screen, subs="{sub-order}"]
....

// Get all of the remotes
$ git pull origin
// Create a local tracking branch (if you haven't already)
$ git branch --track release-9 refs/remotes/origin/release-9
// Check out your local tracking branch.
$ git checkout release-9
// Merge from master into the branch (this becomes your point in time
// from master that you will be releasing from)
$ git merge --no-ff master

        
....
3.  Update the VERSION.txt with changes from the git logs, this populates the resolves issues since the last release.
+
[source, screen, subs="{sub-order}"]
....

$ mvn -N -Pupdate-version        

        
....
4.  Edit the VERSION.txt file to set the 'Release Version' at the top alongside the Date of this release.
+
[source, screen, subs="{sub-order}"]
....

$ vi VERSION.txt        

        
....
5.  Make sure everything is commit'd and pushed to github.com/eclipse/jetty.project
+
[source, screen, subs="{sub-order}"]
....

$ git commit -m "Updating VERSION.txt top section" VERSION.txt
$ git push origin release-9        

        
....
6.  Prepare the Release
+
NOTE: This step updates the <version> elements in the pom.xml files, does a test build with these new versions, and then commits the pom.xml changes to your local git repo.
The `eclipse-release` profile is required on the prepare in order to bring in the jetty aggregates as that profile defines a module which is ignored otherwise.
+
[source, screen, subs="{sub-order}"]
....

$ mvn release:prepare -DreleaseVersion=9.0.0.v20130322 \
                      -DdevelopmentVersion=9.0.1-SNAPSHOT \
                      -Dtag=jetty-9.0.0.v20130322 \
                      -Peclipse-release        

        
....
7.  Perform the Release
+
NOTE: This step performs the release and deploys it to a oss.sonatype.org staging repository.
+
[source, screen, subs="{sub-order}"]
....

$ mvn release:perform

        
....
8.  Set up files for next development versions.
+
Edit `VERSION.txt` for 'Next Development Version' at the top.
Do not date this line.
+
Make sure everything is commit'd and pushed to github.com/eclipse/jetty.project
+
[source, screen, subs="{sub-order}"]
....

$ vi VERSION.txt
$ git commit -m "Updating VERSION.txt top section" VERSION.txt
$ git push origin release-9

        
....
9.  Close the staging repository on oss.sonatype.org
10. Announce stage to the mailing list for testing.
11. Once the staged repository has been approved by the rest of the committers.
+
* Release the staging repository to maven central on oss.sonatype.org
* Merge back the changes in release-9 to master
+
[source, screen, subs="{sub-order}"]
....

$ git checkout master
$ git merge --no-ff release-9
$ git push origin master

            
....

[[releasing-aggregates]]
==== Building and Deploying Aggregate Javadoc and Xref

Define the jetty.eclipse.website server entry in your .m2/settings.xml file.
You'll need to have access to the dev.eclipse.org machine to perform these actions.
If you don't know if you have access to this then you probably don't and will need to ask a project leader for help.

To build and deploy the aggregate javadoc and jxr bits:

[source, screen, subs="{sub-order}"]
....

$ cd target/checkout
$ mvn -Paggregate-site javadoc:aggregate jxr:jxr
$ mvn -N site:deploy   

    
....

This will generate the aggregate docs and deploy them to the `/home/www/jetty/<project version>/jetty-project` directory on download.eclipse.org.

[[releasing-distributions]]
==== Deploying Distribution Files

Since we also provide alternative locations to download jetty distributions we need to copy these into place.
There are a couple of scripts that will take care of this although they need to be localized to your particular execution environment and you need to have authorization to put stuff where it needs to go.
These scripts are located at:

* http://git.eclipse.org/c/jetty/org.eclipse.jetty.admin.git/tree/release-scripts.

To localize the scripts to your environment:

* ensure you have "curl" installed
* edit the scripts and replace all ssh login lines with your own login id

Once these are setup you can deploy a release to eclipse with the following incantation:

[source, screen, subs="{sub-order}"]
....

$ ./promote-to-eclipse.sh 9.0.0.v20130322
    
....

Each of these scripts will download all of the relevant files from maven central and then copy them into the correct location on eclipse infrastructure.
On the eclipse side of it they will also adjust the xref and javadoc documentation links if they remain broken as well as regenerate all of the html files on the eclipse download site.

[[releasing-stable-links]]
==== Updating Stable Links

Since we are not allowed to have symbolic links on the download site we have to log into the machine manually and remove the previous stable directory and update it with a new release.
Maintaining the conventions we use on the site will allow all 'stable' links to be stable and not needed to update to the latest major Jetty build version:

[source, screen, subs="{sub-order}"]
....

$ ssh <user>@build.eclipse.org
$ cd ~downloads/jetty/
$ rm -Rf stable-9
$ cp -r <version> stable-9
$ ./index.sh   

    
....

This needs to be done for all Eclipse Jetty releases (regardless of version). In addition we have to work to reduce the footprint of jetty on the primary eclipse download resources so we want to move older releases to the eclipse archive site.

[source, screen, subs="{sub-order}"]
....

$ cd ~/downloads/jetty
$ mv <old release> /home/data/httpd/archive.eclipse.org/jetty/    
$ ./index.sh   

    
....

Periodically we need to do the same for the osgi P2 repositories to keep the size of our downloads directory at a reasonable size.

==== Building an OSGi P2 Repository

Most of the jetty jars are also osgi bundles, plus we release some specific bundles that link:#framework-jetty-osgi[integrate jetty closely with osgi].
To do this, we use a Hudson job on the eclipse infrastructure. You will need to have permission to access https://hudson.eclipse.org/hudson/view/Jetty-RT/

There are Hudson jobs that build osgi p2 repos for each of the major releases of jetty:7 (jetty-rt-bundles-7), 8 (jetty-rt-bundles-8) and 9 (jetty-rt-bundles-9).
You will need to start a manual build of the job that matches the version of jetty that you are releasing.
You will be prompted to supply some parameters to the build:

pack_and_sign::
  By default, this is ticked. Leave it ticked.
jetty_release-version::
  Enter the version number of the release, eg 9.2.6.v20141205
force_context_qualifier::
  Leave this blank.
set_pom_version::
  Enter the major.minor.point release number, eg 9.2.6
delete_tycho_meta::
  This is ticked by default. Leave it ticked
BRANCH_NAME::
  This is not the branch of the jetty release. Rather it refers to the branch structure of the project that drives the jetty p2 release.
  It will already be set correctly for the selected job, so don't change it unless you have an extremely good reason.

Once you have supplied the necessary parameters, the build job will commence and the bundles and update site zips will generated and automatically placed in the `/home/data/httpd/downlaod.eclipse.org/jetty/updates/jetty-bundles-[MAJOR.VERSION].x`, where [MAJOR.VERSION] matches the major version number of the jetty release you are doing.
These files will then be visible from http://download.eclipse.org/jetty/updates/jetty-bundles-[MAJOR.VERSION].x, where [MAJOR.VERSION] corresponds to the major version of the jetty release you are doing.

[[releasing-documentation]]
==== Release Documentation

There are two git repositories you need to be aware of for releasing jetty-documentation. The jetty-documentation is located in our github repository and the jetty-website is located at eclipse.

jetty-documentation::
  https://github.com/jetty-project/jetty-documentation
jetty-website::
  http://git.eclipse.org/c/www.eclipse.org/jetty.git

Do the following steps to publish documentation for the release:

1.  Checkout the jetty-documentation repository.
2.  Edit the <version> of the jetty-documentation pom.xml and change it _locally_ to be the release number, eg 9.2.6.v20141205
3.  Build the documentation with mvn clean install
4.  Checkout the jetty-website
5.  Inside the documentation/ directory, make a directory named the same as the release number, eg 9.2.6.v20141205/
6.  Copy the built `documentation` from jetty-documentation/target/docbkx/html/jetty into the new directory
7.  Edit the `index.html` file in the `documentation` directory and add the newly released documentation url.
Make sure you follow the other examples and include the `rel="nofollow"` attribute on the link so that search engines do not crawl newly created documentation, otherwise we are subject to duplicate content penalties in SEO.
8.  Commit the changes to the jetty-website project

____
[NOTE]
There is a separate Jenkins build job that publishes documentation to http://www.eclipse.org/jetty/documentation/current triggered by a push of changed files to the jetty-documentation project.
If you commit your change to the <version> number from step 2, then these builds will use the same release version number.
It is preferable if you _don't_ commit that version number change, or better yet, ensure that it is set to the next -SNAPSHOT version number for your jetty major release number.
____