Title: Apache Velocity Release Process

## Velocity Release Process

Here you will find the steps to create releases for Velocity Engine or Velocity Tools.

Instructions make explicit references to the *engine* subproject, but you can easily adapt them for the *tools* subproject.

*Note - since Velocity repositories switched from svn to git, part of the following information has to be updated accordingly.*

### Prerequisites

To create a release you have to install:

* [Java Development Kit 8](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
* [Maven 3](http://maven.apache.org/)
* [GnuPG](http://www.gnupg.org/)
* [OpenSSH](http://www.openssh.com/}OpenSSH)

### One-time operations

These operations need to be performed only one time.

* Create and publish your GPG key

    To create a GPG key, follow the [guidelines](http://www.apache.org/dev/openpgp.html}guidelines). Insert in the file you find on people.apache.org at the directory:
    
        /www/www.apache.org/dist/velocity/

	Publish your GPG key in a PGP key server, such as [MIT Keyserver](http://pgp.mit.edu/).

* Modify `settings.xml`
    
    Your `settings.xml` must be modified to allow deployment.
    
    This is the minimal configuration, obviously if you already have a `settings.xml` file, you must edit it:
    
         :::xml
        <settings xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
			http://maven.apache.org/xsd/settings-1.0.0.xsd">
		  <servers>
            <server>
              <id>apache-site</id>
              <username>YOUR_APACHE_USERNAME</username>
              <filePermissions>664</filePermissions>
              <directoryPermissions>775</directoryPermissions>
            </server>
            <server>
              <id>apache.snapshots.https</id>
              <username>YOUR_APACHE_USERNAME</username>
              <password>YOUR_APACHE_PASSWORD</password>
            </server>
            <server>
              <id>apache.releases.https</id>
              <username>YOUR_APACHE_USERNAME</username>
              <password>YOUR_APACHE_PASSWORD</password>
            </server>
          </servers>
		  <profiles>
            <profile>
              <id>apache-release</id>
              <properties>
                <gpg.keyname>YOUR_KEY_NAME</gpg.keyname>
                <gpg.passphrase>YOUR_SECRET_PHRASE</gpg.passphrase>
              </properties>
              </profile>
            </profile>
          </profiles>
        </settings>
    

### Repeatable operations

These steps must be performed **for each** release.

* Check updates of dependencies and maven plugins:

        :::shell
        mvn versions:display-dependency-updates
        mvn versions:display-plugin-updates

* Check content of root README.md file (for new features documentation, important notices, and stated dependencies versions).

* Also check updates for the parent velocity-master artifact version.

* Archive the previous release candidate

    If it's not the first release candidate you're trying to release, you should archive the previous release candidate. For instance:
    
        :::shell
        svn mv -m "[engine] archive engine 2.0 RC4" https://_your_apache_id_@svn.apache.org/repos/asf/velocity/engine/tags/2.0 https://_your_apache_id_@svn.apache.org/repos/asf/velocity/engine/tags/2.0-RC4
    
    And don't forget to also drop the staged artifact.
    
    Of course, you will also have to revert the automated commits from the previous `mvn release:*` commands. You can use the following shell one-liner to get their revision numbers:
    
        :::shell
        $ svn log pom.xml | grep -B2 maven-release-plugin | egrep "^r" | head -2 | cut -d' ' -f 1
        r1866626
        r1866624
    
    Then, revert:
    
        svn merge -r1866626:1866623 .
        svn commit -m "[engine/tools] Revert poms for next 2.2 RC attempt"


* Complete and update the changelog source file `src/changes/changes.xml` (note: we may get rid of this changelog in the future since it is quite painful to maintain and seems highly redundant with the JIRA release notes).

* Prepare the release tag
    
    To prepare the release Subversion tag, check out the branch/trunk from where
    you are preparing the release and type:
    
        :::shell
        mvn release:prepare -Dusername=YOUR_SVN_USER -Dpassword=YOUR_SVN_PASSWORD
    
    The plugin will interactively ask you the version to release, the subversion tag to use and the next snapshot version. Rather than the proposed default `velocity-engine-parent-X.X`, we tend to use X.X for the subversion tag.

* Perform the release
    
    To perform the release, i.e. creating and deploying Maven artifacts, use:
    
        :::shell
        mvn release:perform

* Stage the release

    Commit all poms (renamed from `<module>/pom.xml` to `module-<version>.pom`), binary, sources, javadoc jars in the proper subdirectory of the [release staging area](https://dist.apache.org/repos/dist/dev/velocity) svn repository, along with their signature files (*.asc), which have been generated under the `target/checkout` folder.

* Provide sha-256 checksums

    Create sha-256 checksums for each pom/jar/asc file on the 
    
        :::shell
        for file in *.jar *.asc *.pom; do sha256sum < $file > $file.sha256; done
    
    and add those files to the release staging area svn repository.

* Release the JIRA version
    
    * In JIRA go to the version that you want to release and release it.
        
    * Create a new version, if it has not been done before.
        
    * Create the JIRA release notes and **copy the content** inside your pretty release notes HTML file, which is to be hosted under svn on the same release staging area.

* Close the staging repository
    
    Login to [Nexus repository](https://repository.apache.org) using your Apache LDAP credentials.
	
    Click on "Staging". Then click on "velocity" in the list of repositories.
	
    In the panel below you should see an open repository that is linked to your username and ip.
	
    Right click on this repository and select "Close".
	
    This will close the repository from future deployments and make it available for others to view.
	
    If you are staging multiple releases together, skip this step until you have staged everything.
	
    Enter the name and version of the artifact being released in the "Description" field and then click "Close".
	
    This will make it easier to identify it later.

* Verify the staged artifacts
    
    If you click on your repository, a tree view will appear below.
	
    You can then browse the contents to ensure the artifacts are as you expect them.
	
    Pay particular attention to the existence of *.asc (signature) files.
	
    If you don't like the content of the repository, right click your repository and choose "Drop".
	
    You can then rollback your release and repeat the process.

    Note the repository URL, you will need this in your vote email.    

* Prepare the site

    Copy the `/devel/` section to its `<version>` section (but do not yet refence it from the menu), and fix any SNAPSHOT link within.
    
    Generate the corresponding javadoc with
    
        :::shell
        mvn javadoc:aggregate
    
    and commit the result in [VERSION]/apidocs
    
    Push those changes to production (see the [Site Building](http://velocity.apache.org/site-building.html) page).

* Send announcement for the test build

    In **developers mailing list** send an announcement for the test build:
    
    (note: in all the following, ${module} refers to the module -Engine or Tools- being released, ${version} to the version)
        
        Subject: [ANNOUNCE] Velocity ${module} ${version} test build available
        
        The test build of Velocity ${module} ${version} is available.        
        
        No determination as to the quality ('alpha,' 'beta,' or 'GA') of Velocity ${module} ${version} has been made, and at this time it is simply a "test build". We welcome any comments you may have, and will take all feedback into account if a quality vote is called for this build.
        
        Release notes:
        
        * https://dist.apache.org/repos/dist/dev/velocity/.../release-notes.html
        
        Distribution:
        
         *  https://dist.apache.org/repos/dist/dev/velocity/.../
        
        Maven 2 staging repository:
        
         * https://repository.apache.org/content/repositories/velocity-[YOUR REPOSITORY ID]/
        
        Documentation:
        
        * https://velocity.apache.org/${module}/${version}
        Sources:
        
         * https://svn.apache.org/repos/asf/velocity/${module}/tags/${version}
        
        A vote regarding the quality of this test build will be initiated within the next couple of days.

* Call for a vote
    
    A few days after the test build announcement, call for a vote in **developers mailing list**.

        Subject: [VOTE] Velocity ${module} ${version} Release Quality
        
        The Velocity ${module} ${version} test build has been available since ${testBuildDate}.
        
        Release notes:
        
        * https://dist.apache.org/repos/dist/dev/velocity/.../release-notes.html
        
        Distribution:
        
         *  https://dist.apache.org/repos/dist/dev/velocity/.../
        
        Maven 2 staging repository:
        
         * https://repository.apache.org/content/repositories/velocity-[YOUR REPOSITORY ID]/
        
        Sources:
        
         * https://svn.apache.org/repos/asf/velocity/${module}/tags/${version}
        
        If you have had a chance to review the test build, please respond with a vote on its quality:
        
         [ ] Leave at test build
         [ ] Alpha
         [ ] Beta
         [ ] General Availability (GA)
        
        Everyone who has tested the build is invited to vote. Votes by PMC members are considered binding. A vote passes if there are at least three binding +1s and more +1s than -1s.

### Post-vote operations
    
After a vote is finished, and it has been decided that is **at least of alpha quality**, there is the need of a post-vote process.
    
* Promote staged artifacts
    
    Once the release is deemed fit for public consumption it can be transfered to a production repository where it will be available to all users.
    
    Login to [Nexus repository](https://repository.apache.org) again.
	
	Click on "Staging" and then on the repository with id "velocity-staging".
	
	Find your closed staging repository, right click on it and choose "Promote".
	
	Select the "Releases" repository and click "Promote".
	
	Next click on "Repositories", select the "Releases" repository and validate that your artifacts exist as you expect them.

* Publish the release

    Copy the staged release to the Apache Releases svn repository at https://dist.apache.org/repos/dist/release/velocity/{module}/...
    
    You may subsequently receive an automated email from the Apache Reporter Service asking you to log on to https://reporter.apache.org/addrelease.html?velocity to add the release metadata to its database. Please do so.

* Update the site
        
    Wait 24 hours to let the mirror sync to the release and then update the site.
    
    Update the download page, the left menu, the news section, and the engine or tools index:
    
        velocity/site/cms/trunk/content/download.mdtext
        velocity/site/cms/trunk/content/left.nav
        velocity/site/cms/trunk/content/news.xml
        velocity/site/cms/trunk/content/${module}/index.mdtext
        velocity/site/cms/trunk/content/index.mdtext (status section)
        
    Push the changes into production.   
    
    Check the resulting site for broken links
    
        :::shell
        wget --spider -r -nd -nv -H -l 2 -w 2 -o links.log https://velocity.apache.org/

* Update the DOAP RDF project metadata located under `svn.apache.org/repos/asf/velocity/site/site\.

* Send announcement
        
    Finally, send an an announcement to users@, dev@, general@ velocity.apache.org and at announce@ apache.org (in text-only format and using your @apache.org committer email, see [how to configure your SMTP client](https://reference.apache.org/committer/email)), by adapting the following canevas:
        
        Subject: [ANNOUNCE] Velocity ${module} ${version} ${quality} Released
        
        The Apache Velocity team is pleased to announce the release of Velocity ${module} ${version} ${quality}.

        [insert here a short description of the ${module}, aka:]

            Velocity is a Java-based template engine. It permits anyone to use a simple yet powerful template language to reference objects defined in Java code.

        [or]

            Velocity Tools is a library of template tools and helpers to ease the use of the Apache Velocity template engine in standalone applications and in webapps.
        
        [insert here a short description of the main changes]

        For a complete list of changes, please visit the Velocity ${module} ${version} releases notes [1].
        
        For notes on upgrading from Velocity ${module} ${previous-version}, see Velocity ${module} Upgrading section [2].

        Velocity ${module} ${version} is available in a binary and a source distribution [3].
        
        http://velocity.apache.org/download.html#${module}
        
        It is also available in the central Maven repository under Group ID "org.apache.velocity[.tools]".        
        
        Please feel free to test the distribution and post your comments to the user list [4], or, if appropriate, file a ticket with JIRA [5].
        
        Regards,
       
          the Apache Velocity community.

        [1]: http://www.apache.org/dist/velocity/${module}/${version}/release-notes.html
        [2]: http://velocity.apache.org/${module}/${version}/upgrading.html
        [3]: http://velocity.apache.org/download.cgi#${module}
        [4]: http://velocity.apache.org/contact.html#mailing-lists
        [5]: https://issues.apache.org/jira/projects/[VELTOOLS or VELOCITY]

**You have finished!**