Project Maintanance Howto
-------------------------
This document introduces newcomers to the management and maintenance of
the Batik project hosted under xmlgraphics.apache.org
(http://xmlgraphics.apache.org/batik).
Each project is required to use Ant as build tool and to be coherent with the
rest of the build systems of the other projects, so that nightly builds and
distribution creation can be done automatically without per-project scripts.
This implies it is *very* important that properties names are not changed
but kept consistent with the other projects.
Distribution Creation
---------------------
For creating a distribution the following steps must be done:
1) Modify build.xml with the distribution version. Only modify the version
for main releases (e.g. version value="1.1") but not for release
candidates or beta versions where only the revision type and
number should be updated (e.g. revisionType value="beta" and
revisionNumber value="3")
2) Add your public key to the KEYS file in the root directory of
Batik if it isn't already there. The following link has the
details on what this means and how to do it.
http://wiki.apache.org/old/SigningReleases
3) Commit these changes to SVN, in general only the following files
should be modified:
build.xml
KEYS
4) Tag the release on SVN:
svn copy https://svn.apache.org/repos/asf/xmlgraphics/batik/trunk \
https://svn.apache.org/repos/asf/xmlgraphics/batik/tags/<tag>
where <tag> is the version name, e.g. "batik-1_1rc3".
Note: sometimes, it is necessary to remove a tag because the
tests failed and a fix was required. To remove a tag, use
the delete command:
svn delete https://svn.apache.org/repos/asf/xmlgraphics/batik/tags/<tag>
5) Check out the tagged release to a new directory:
svn co https://svn.apache.org/repos/asf/xmlgraphics/batik/tags/<tag>
6) Run the build script with target "dist-zip":
build dist-zip
This will create the binary release zip, the source release zip and the
javadoc zip.
7) Test the distributions
build regard
build regard.manual
The build results are in the test-reports directory. Check that there
are no show-stoppers for the release. If there are fixes required,
you need to remove the tag (as explained in step 2) and then fix
any problem that requires attention. Then, you need to start at
step 1) again.
Note that you will need to have a copy of the W3C SVG
working group test suite in the 'beSuite' directory and
have that directory under the same root as xml-batik. See
http://www.w3.org/Graphics/SVG for instructions on how to get
the SVG test suite.
8) Update the README and CHANGES files describing the content of the
release and the modifications which have taken place,
http://www.apache.org/dist/xmlgraphics/batik/README. This file has a
small header followed by the contents of the CHANGES file from the
distribution.
9) If you are creating a release candidate, rename the distribution files
to an rc name. For example:
mv batik-src-1.1.zip batik-src-1.1rc1.zip
10) Sign and create md5 hashes for the releases. The following link
has full details on how to sign things (if you don't want to know
anything the last section 'Using GPG' tells you what commands work).
http://wiki.apache.org/old/SigningReleases
For example:
gpg --detach-sig --armor --output batik-1.5.zip.asc batik-1.5.zip
md5 batik-1.5.zip > batik-1.5.zip.md5
11) Use 'scp' to copy the distributions (with md5 hashes, and signature
files), the README, and the KEYS file under
/www/www.apache.org/dist/xmlgraphics/batik/
For example:
scp batik-1.1rc1.zip* vhardy@people.apache.org:/www/www.apache.org/dist/xml/batik/
12) Finish setting up the distribution directory in accordance with:
http://www.apache.org/dev/mirrors.html
http://people.apache.org/~bodewig/mirror.html
This makes sure that the distribution is mirrored nicely around
the world.
Start by logging into svn.apache.org (e.g. 'ssh vhardy@svn.apache.org').
First make sure file permissions are correct. The
new files should be owned by group 'xmlgraphics' and be group writable.
The following commands can do this (don't worry about links):
chgrp xmlgraphics batik-1.5.zip
chmod 664 batik-1.5.zip
If you are making a 'final' release you should delete the existing
'current' links and re-point them at the new release (do this
for every file with a version number in it - including md5, and
asc files):
cd /www/www.apache.org/dist/xmlgraphics/batik
rm batik-current.zip
ln -s batik-1.5.zip batik-current.zip
rm batik-current.zip.md5
ln -s batik-1.5.zip.md5 batik-current.zip.md5
rm batik-current.zip.asc
ln -s batik-1.5.zip.asc batik-current.zip.asc
<- lots more files ->
Finally remove the old releases (every release is automatically copied
to 'archive.apache.org/dist/xmlgraphics/batik' from
'www.apache.org/dist/xmlgraphics/batik' so you can just remove an old
release from www.apache.org:
rm batik-1.5b4.zip
13) Wait approximately 24hrs for the files to get to all the mirrors,
then send an email to the batik-dev and batik-users mailing lists
announcing the release.
Site Creation
-------------
For creating the web site, the following steps must be done:
[Note: due to JVM font-rendering problems, this is best done on a
windows machine]
1) run the build script with target "publish", which will generate the
site and use ForrestBot to commit it to the repository
2) connect to people.apache.org with your account
3) execute "cd /www/xmlgraphics.apache.org/batik"
4) execute "svn update"
If the javadocs don't need to be regenerated, the "publishdoc" build
target can be used instead of "publish". This will be much quicker.
Note that because of the way ForrestBot works, any files that are no
longer part of the site will still remain in Subversion, and thus will
still be deployed. To delete files permanently, check out
https://svn.apache.org/repos/asf/xmlgraphics/site/deploy/batik/ and make
changes there directly.
Nightly Builds
--------------
The nightly builds are current performed by a crontab entry in
Thomas DeWeese's people.apache.org account: /home/deweese/bin/nightly.csh
