| 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!** |
