



































|
 |
The product build
related sections of this document are still quite thin - they're
mainly bullet points almost in checklist style. If you don't fully
understand the procedures in this document, then you probably
should ask for help first! |
|
|
A
selection of brief checklists for committers and developers about
build procedures for the Xalan-Java community. Community input is
appreciated; if you have questions, please ask on
xalan-dev.
|
|
|
GUMP is...
there really is no easy way to define 'GUMP'. It's basically a
meta-build system designed to do CVS updates and Ant builds of
multiple projects simultaneously. Luckily, GUMP is a subproject of
jakarta-alexandria that includes a complete set of GUMP
documentation.
Some
committers at jakarta also provide a GUMP service, which runs
actual builds nightly of nearly all xml and jakarta projects. The
results of nightly
builds are posted daily, and the actual Xalan-Java
nightly build is also posted (when it succeeds).
Discussions about GUMP itself
happen on the alexandria-dev@jakarta.apache.org mailing list. Note:
nightly builds are just that - automated builds run nightly,
without human intervention. Use them at your own risk!
|
 |
 |
 |
 |
Running Product Builds -
Details |
 |
 |
 |
 |
|
|
This
section is still in progress, but should have all the basics. You
should already have read the build
overview above and you should already be familiar with our
build.xml script and development processes.
|
|
Preparation before you run a build.
- Email xalan-dev with build plan.
Apache projects are communities: you should always let
the community know what the plans for builds are. The xalan-dev
mailing list is the primary communication mechanisim for committers
and developers working on Xalan-Java; you may also wish to cc: the
xalan-j-users list to let other users and folks know what's coming.
For major releases you may also want to cc: the
general@xml.apache.org list so that other xml.apache.org projects
know our plans, although this is not required.
- Verify all code changes are checked in.
Ensure that any code changes you're planning to have in
this release are actually checked in; make sure any open work by
other committers is in a stable state. You should also review any
other projects we're dependent on and make sure that (when
possible) we've updated to the latest version of their .jar files:
like xercesImpl.jar, ant.jar, etc. Note that occasionally we will
have a specific development need to stay with a different version
of these projects.
|
 |
 |
 |
 |
Updating Doc And Version
Numbers |
 |
 |
 |
 |
|
|
Getting documentation and version numbers in
sync.
- Verify any doc updates for code changes are
in.
Check that the documentation is up to date. Make sure
that any new features or major functionality changes are properly
documented.
Update the commits list and the 'what was done' list in
xdocs/sources/xalan/readme.xml and whatsnew.xml. Note that
currently some of the status information for the XSLTC portion of
Xalan-Java is stored separately in xsltc_history.xml and
XSLTCDONE
Check in all your work!
- Update build numbers in doc, code, and build
scripts.
Currently the actual version number is stored in several
places in the CVS tree - we hope to improve this in the future by
using the Ant build system's filtering capabilities.
Once you know what the version number should be, you'll
need to update it in a number of places - both for the product
itself, for the build system, and for the documentation. If you
don't understand how to update any of these files, then please get
help - don't just try to wing it.
 |
Version.java should
replace XSLProcessorVersion.java; we just haven't gotten around to
doing it yet... -Shane |
- src/org/apache/xalan/Version.java (The NEW 2.2+ actual
code version of the processor - currently just a wrapper for
XSLProcessorVersion, which is deprecated and will be removed after
2.2 gold ships in favor of the simpler Version class, which uses
static accessor methods instead of static strings)
- src/org/apache/xalan/processor/XSLProcessorVersion.java
(The old 2.2 and earlier actual code version of the processor)
Update the int format VERSION, RELEASE, MAINTENANCE, and
DEVELOPMENT numbers, each as an integer. The version string will be
automagically built from these.
- build.xml Update the following lines for each version
field:
<property name="version.VERSION" value="2"/>
<property name="version.RELEASE" value="4"/>
<property name="version.DEVELOPER" value="D"/><!-- Set
this to "D" if a developer release; blank "" if maintenance point
release --> <property name="version.MINOR"
value="1"/><!-- EITHER the developer release number, or a
maintenance point release number -->
- src/org/apache/xalan/res/XSLTInfo.properties:
Update the version number.
- xml-xalan/java/xdocs/sources/entities.ent
(xslt4j-current, xslt4j-dist) documentation updates. The xsl4j-dist
is used to construct links to the actual distribution units, and
must be coordinated with whatever xml-xalan/java/build.xml uses for
${version}.
- If you updated xercesImpl.jar or any other dependent .jar
files, make sure you update the documentation to reflect this.
xml-xalan\java\xdocs\sources\entities.ent (xml4j-used)
- xml-xalan/java/xdocs/sources/xalan-jsite (document
id="index" label="Xalan-Java x.x")
I did remind you to check in all your work, didn't
I?
|
 |
 |
 |
 |
Run A Candidate Distribution
Build |
 |
 |
 |
 |
|
|
Get clean sources and build a distribution and (at least)
the smoketest.
- Do a clean checkout and tag the sources.
Of course, you checked in all your earlier work to the
CVS repository, right?
The safest way to perform a build for distribution is to
check out a fresh new copy of the repository from CVS. This avoids
any potential problems with uncommitted changes or extra files on
your local machine.
Check out a new copy of both xml-xalan/java and
xml-xalan/test repositories to a blank directory on your local
machine. You then need to tag the files in the repository with a
marker noting that these versions are the actual ones being used in
the build (you could actually do this after running the build
below). Use the CVS tag command to add the tag to both repositories
(/java and /test). The tag name should be something like
'xalan-j_2_4'; look at the log of any file to see the exact format
of previous builds.
- build dist site smoketest -logfile
..\dist.log
The above command will build the 'dist' or distribution
.zip/.tar.gz files, as well as building the full product plus all
documentation. It will then run the smoketest, and saves all of
it's output in ..\dist.log. Note that this will take up a moderate
amount of space, especially when building the .tar.gz files, so
ensure you have plenty of disk space first.
- Verify smoketest passed; check docs built with new build
numbers.
Review the dist.log quickly to ensure there were no build
errors. Note that you can ignore any 'warnings' from the javadoc
target; however any 'error's in the documentation must be
fixed.
The logfile should also report the Smoketest results at
the end; if it does not say that the Smoketest passed, then you
must fix the test results before posting the build. Even for
developer's builds, we must ensure that at least the Smoketest
passes. For major or minor releases, we should also perform more
testing to ensure stability. More detailed log files for the
Smoketest can be found in the xml-xalan/test/smoketest/
directory.
You should also test that the documentation built
properly, and that it has the proper build or release number that
you edited above.
IMPORTANT: if you changed any files at all, be sure to
check in your work and re-start this process!
|
|
|
Sign the distribution units so end-users can trust them,
then copy to the website.
- PGP/GPG sign all .zip/.tar.gz distribution files
(distros).
As a security measure, all xml.apache.org projects must
sign or otherwise ensure the integrity of their public
distributions. This is most commonly done by signing the actual
.zip/.tar.gz files with your personal PGP or GPG key. Note that you
must sign the files before copying them up to the
website.
Two prerequisites to signing the distribution are: 1) you
must have a personal PGP or GPG key, and 2) the public half of your
key must be in the appropriate KEYS file before you begin a build.
If you hadn't previously checked in your public key to the KEYS
file before beginning this whole process, you'll have to go back
and start again.
 |
We need some good
links on getting PGP and GPG, and on actually code signing
and verifying signatures. Jakarta has some, but they're scattered.
This would be a good volunteer project for someone. |
Sign every .zip and .tar.gz file with your personal key,
and make a detached text file with the signature - this will
usually create a foo.zip.asc or foo.zip.sig file for each foo.zip
file you sign.
- Copy distros up to the website.
You'll need to copy all of the distros plus all of your
detached signature files to the website so people can download
them. Note that apache.org machines generally do not allow inbound
ftp, so you'll need to either scp them or login to the apache
machines and use scp or pftp from there outbound to some server
that you've copied them to.
(Subject to change as www.apache.org/dist gets ready for
mirroring) You'll need to log on to xml.apache.org (which is a
separate machine from cvs.apache.org) and upload the files to
/www/xml.apache.org/xalan-j/dist
You should also update the distribution directory's html
files to note the new build numbers. Carefully edit the .htaccess
file to update the 'Latest Stable Build' and 'Latest Developers
Build' lines as needed. If you don't understand the format of this
file, ask for help.
|
|
|
|