The information on this page is intended for Velocity committers, not as end-user documentation.
(Note - some of the specific instructions this document are out of date now that Velocity has left Jakarta and gone TLP. In particular this applies to details on the Velocity site).
The Velocity project currently is built using Apache ant. This is the canonical build and in case of doubt, the results of this build win. While it is possible to build Velocity using Apache maven, the inherently instable nature of Maven 1.x and the not yet proven reliablity of Maven 2.x make us feel that maven is not yet 'ready' to be used as primary build tool for Velocity.
Velocity up to and including Version 1.4 uses only Apache ant as its build tool. Starting with Velocity 1.5, we will still build the actual release archives with ant but nightly builds and especially the web site located at http://velocity.apache.org/ will be built using Apache maven V1. Using Maven buys us a number of interesting reports and metrics during the build process (such as automated Changelogs, metrics, web-formatted test reports and so on).
Apache Maven uses a XML file called project.xml
and a number of properties files to control its build process.
Purpose |
File system location (on minotaur) |
web location |
Release location |
/www/www.apache.org/dist/velocity/engine |
Mirrored through the Apache mirror system, available through http://velocity.apache.org/download.cgi |
Maven repository release location |
/www/www.apache.org/dist/java-repository/velocity |
http://www.apache.org/dist/java-repository/velocity/ |
Maven repository snapshot location |
/www/cvs.apache.org/repository/velocity |
http://cvs.apache.org/repository/velocity/ |
Due to the fact that deployment happens to the Apache web staging server from which the actual servers (which are velocity.apache.org) mirror the content every few hours or so, changes are not immediately visible. If you want to check whether the content arrived ok on the apache server, use the 209.237.227.195 trick (which is using the IP address and port 80 as your proxy host. Then access http://velocity.apache.org/ and you get the content directly from minotaur).
There are two deployment repositories defined in project.properties
:
# Repository for official releases maven.repo.apache=scpexe://cvs.apache.org maven.repo.apache.directory=/www/www.apache.org/dist/java-repository # Repository for alpha, beta, rc releases maven.repo.snapshot=scpexe://cvs.apache.org maven.repo.snapshot.directory=/www/cvs.apache.org/repository/velocity |
The selection of the repository happens through the maven.repo.list
parameter. It defaults to the snapshot repository.
Q: Why are we using 'scpexe' and not 'scp' for deployment?
A: Because for Apache logins, according to infrastructure, we should stick to public/private key authentication to access the distribution servers. In that case, you would have to give the full path to your private key and also the passphrase on the command line. E.g. like this:
maven -Dmaven.repo.snapshot.privatekey=/home/henning/.ssh/id_dsa -Dmaven.repo.snapshot.passphrase=verysecret dist:deploy |
Q: Why that? What about ssh-agent
or pageant
?
A: You will have to google for that answer quite a while. Here is the short answer: ssh-agent
uses an unix domain-socket which cannot be accessed in pure Java. End of Story.
Q: scpexe:// does not work for me!
A: You have to add the following properties to your global (~/.build.properties
on Unix) properties file:
maven.username= <your apache login> maven.ssh.args=-o ForwardX11=false |
I needed the last line to get scpexe to run on RedHat (Fedora) Linux.
After setting up your global build properties file as described above, you should be able to run the following commands:
Please note that due to a design problem in the artifact plugin of maven, the jar or distribution archive and the related POM can have (will have if you have a slow line) different time stamps. So the POMs are basically useless.
As we currently build official releases with ant, this paragraph is intentionally empty.
changes.xml
has the most recent updates listed.svn update
to get the most recent tree for release.svn status
should be empty.bin
and target
directories.build
directory
build.properties
to reflect the version to be released.changes.xml
, changing the version
attribute of the topmost release
tag to indicate the most version number to be released.svn commit
ant release
(this is related to ant package
but checks for the right version of Java).bin
directory#! /bin/bash for i in *.tar.gz *.zip *jar; do gpg --default-key <your key id here> --armor --output $i.asc --detach-sig $i done |
You should now have sixteen files in that directory: A .jar, a .jar with dependencies, a .tar.gz and a .zip file. For each you must have a .md5, a .sha1 and a .asc file. If you file count is not correct, please DO NOT CONTINUE.
umask 002
/www/www.apache.org/dist/velocity/engine/velocity-<new version>
. Make sure that its permissions are set to 775!Now that the release is out, please let the mirrors some time to pick up the releases. In the meantime, please do the following preparations to make the release public.
svn copy -m 'Release <released version>' https://svn.apache.org/repos/asf/velocity/engine/trunk https://svn.apache.org/repos/asf/velocity/engine/tags/ENGINE_<released_version> |
(The older tags are a bit in disarray. This will get cleaned up in the future).
(This section is out of date)
bin
and target
directories one more time.project.xml
to the release version<version> <name>1.5</name> <tag>ENGINE_1.5</tag> <id>1.5</id> </version> |
maven site:deploy
project.xml
by running svn revert project.
.../releases/engine/<release version>
.
(This section is out of date)
build.properties
to read <released version + 1>-dev. Check this change in immediately using svn commit build.properties
!
svn checkout https://svn.apache.org/repos/asf/jakarta/site jakarta-site |
ant docs
. CAVEAT: If you do this on an UTF-8 based unix system (e.g. Fedora), you must run this command like this: LANG=en_US ant docs
. Else you will nuke all the non-ascii characters in the site. PLEASE CHECK THIS TWICE BEFORE THE NEXT STEP using svn status
.svn commit
. Even better, please check in only these files anyway.
/www/jakarta.apache.org
and run svn update index.html site
to reflect your changes.
Announcements should have your 'apache.org' email addresse as sender because the first two recipients discard everything not coming from an apache.org address. You should also use the same announcement text (or something closely resembling it) that you put into the news.xml file on the site.