readme-distribution

彩信浏览器

Creating ambulant releases
==========================

This document explains how to cut releases. Doing a release is very boring
and tedious, but please follow these guidelines closely. While getting ready
for a release you should have almost the opposite mindset of during normal
development: only fix what really needs fixing, and please don't be creative.
Also remember that testing is very important. If you decide to save 1 minute
of tedious work by not running all the tests this could well result in another
bug fix release being needed a few weeks later, leading to _days_ of extra
work for everyone (including you:-).

Version numbers, release branches and tags
==========================================

!!=============================================================================!!
!! NOTE: RELEASE 1.8 IS NAMED: release-new-ambulant-18-branch                  !!
!! Any derived tag from this release (merge,bugfix, etc.) has to be named      !!
!! accordingly (release-new-ambulant-18-merge, release-new-ambulant-181, etc.).!!
!!=============================================================================!!

We use a strict numbering scheme for versions. Development versions have
an odd minor number, releases an even one. For example, "1.5" is a development
version, and is a moving target. Once development is finished and we're
getting ready for a release (which will be called "1.6") we create a release
branch called "release-ambulant-16-branch". On this branch, we do the work
described below. Once everything has been tested and the distributions created
(and everything checked in:-) we tag the release branch with tag
"release-ambulant-16". Changes made on the release branch are _not_
propagated to the trunk at this point.

Now we need to merge the changes to the trunk. Set your working copy
to the trunk and "cvs up -jrelease-ambulant-16-branch". Test and commit.

Next, we want to tag the _branch_ to show that we have merged up to here:
set your working copy to the branch, and tag with "release-ambulant-16-merge".

Now go back to the trunk, set version numbers to "1.7" and start working on
wonderful new ideas. But first: do all the tests you did for the release
on the trunk as well, to make sure that all fixes you made on the release
branch have been propagated to the trunk correctly.

Some time later a bug fix release "1.6.1" will have to be done. Switch your working
copy to the "release-ambulant-16-branch" and fix the bugs. Do not add new features,
and only fix critical bugs! Go through the whole distribution and testing
rigamarole explained below. When the releases have been created tag
the branch with "release-ambulant-161". Again, don't propagate fixes to the
trunk just yet.

If at some point you fix something on the trunk but later decide you want that
fix on the release branch too you need to do a bit more. First you merge the
fix to the branch, by doing (on the branch) something like "cvs up -j1.42 xxx.c" (or
a "cvs diff" on the trunk and a "patch" on the branch).
Then you test the fix and check it in (still on the branch). Finally you have to
update the "release-ambulant-16-merge" tag so the fix doesn't get sent back to the
trunk later (which would apply it twice) by doing
"cvs tag -F release-ambulant-16-merge xxx.c".

After the release you need to merge the changes again, but only the ones
you didn't merge previously. Set working copy to the trunk, and
"cvs up -jrelease-ambulant-16-merge -jrelease-ambulant-16-branch". (NOTE:
this has not been tested yet so please take care and modify this sentence if
it turns out to be wrong:-). Finally we need to move the "-merge" tag to
show up to which point the branch has been merged: set your working
copy to the branch, and "cvs tag -F release-ambulant-16-merge" to move
the tag.

A final note: releases 1.4.X and earlier have not followed these guidelines
exactly, the branch and tag names are slightly different (release-ambulant-14
for the branch, release-ambulant-14-tag for the release tag) and the "-merge"
tag was not used.

Before creating the distribution
================================

- make sure your CVS tree is up to date and that there are no uncommited files
- make sure all /*AM_DBG*/ have been changed into AM_DBG
- make sure all the correct renderers are configured (for example the
  quicktime video renderer on the mac)
- change the version number in:
  - configure.in
  - include/ambulant/version.h
  - src/player_macosx/Info.plist
  - src/player_macosx/*.lproj/InfoPlist.strings
  - src/player_wince/AmbulantPlayer.rc
  - src/player_mfc/AmbulantPlayer.rc (Dialog IDD_ABOUTBOX)
  - src/AmbulantWin32Installer/AmbulantWiseInstaller.wse
  	- Product Details->Default Directory
  	- General Information->Installation Version
  	- Add/Remove Programs -> Software Version
  	- Shortcuts
  	- Build Settings -> Installation .exe name
  - src/AmbulantWin32Installer/AmbulantWinCEWiseInstaller.wse
  	- Product Details->Default Directory
  	- Add/Remove Programs -> Software Version
  	- General Information->Installation Version
  	- Build Settings -> Installation .exe name
- check the following files for being up-to-date:
  - README
  - INSTALL
  - Documentation/misc/TIPS-NOKIA770
  - Documentation/misc/README-Distribution (this file)
  - third_party_packages/readme.txt
- Update the icons in the following files:
  - src/player_mfc/res/AmbulantPlayer.ico
  - src/player_wince/res/AmbulantPlayer.ico
  - src/player_macos/cocoambulant.icns
- The sources in src/pyambulant need to be regenerated. Currently this can only
  be done with a Python from cvs, by running "make regenerate-pyambulant".
- Make sure Documentation/API/{refman,html} are empty: we don't want the
  full doxygen output in our source distribution
- You must update NEWS, give a high-level overview of what has changed.
- You must update Changelog. There is a tool cvs2cl that does this
  more-or-less automatically, something like the following command line should
  do the trick:
  
  % cvs log -b -d '>'2004-07-01 | cvs2cl.pl --hide-filenames --stdout --stdin
  (the perl script is on http://www.red-bean.com/cvs2cl/cvs2cl.pl).
  
  Note that if we're preparing for a micro-release you should replace the '-b'
  with -rrelease-ambulant-xxx and merge the output into ChangeLog.

- Update the API documentation in Documentation/API by running doxygen
  Read and check the documentation for consistency, errors and missing items.

- Update the copyright year:
  If a year has passed since the last distribution you must update all licenses and
  other references to the year:
  - See README-Fixlicense for updating the license text
  - Check all places the version number has changed (see above), a lot of them will
    have a copyright year too.
- Update the translations:
  - grep for source files using "gettext" and update POTFILES.in
  - in po, run "make ambulant.pot-update"
  - Then "make en.po" (or "make ../../po/en.po if running in a separate build tree)
    and the same for all other languages.
  - Edit the various ".po" files. Especially check empty strings
    and fuzzy matches.

To create the linux source distribution
=======================================

- Check out a clean copy from CVS, follow the instructions in README-CVS
- Make sure you configure with *all* options (--with-xerces --with-live)
  otherwise not all sources will be included
- Use make distcheck
- If make distcheck complains about not being able to find expat, 
  you have to set the path to the expat library via the environment variable:
 

	DISTCHECK_CONFIGURE_FLAGS="--with-expat=`pwd`/third_party_packages/expat-unix --with-ffmpeg=`pwd`/third_party_packages/ffmpeg-0.4.8" make distcheck
- make dist
- Check on a (preferably virgin) machine, again with all options enabled.
- Check on a Windows machine too! We've had missing windows-only files before:-)
- Check on a Mac too, but this is probably a bit less important.
- Do a "diff -qr" between an unpacked new distribution and an unpacked
  previous distribution. Look at all files that occur only in the old
  but not in the new distribution (and vice versa). For each of those
  determine that this is intended.

Creating the third_party_packages-WIN32 distribution
====================================================

To be supplied.

Binary distribution contents
============================

All binary distribution should contain the following files:
- README
- the player binary, preferable staticly linked
- COPYING (The GNU License)
- DemoPresentation from Extras

Windows desktop also needs:
- Welcome from Extras
- AmbulantPlayerHelp.chm from Documentation/user-htmlhelp

Windows CE needs:
- Welcome from Extras

Zaurus needs:
- Welcome from Extras
- README-ZAURUS from Documentation/misc
- Documentation/user