--------------------------------------------------------------

$Id: release_rules.txt,v 1.24.2.4 2003/08/20 08:10:12 markus Exp $

--------------------------------------------------------------

How to release GRASS binaries and source code

Note: This text contains some rules only applicable to the development
      coordinator (currently Markus Neteler).

--------------------------------------------------------------

General methodolgy: call for release - pre-testing - bug fixes - publish


0. Prepare to create a release

   o Make a list of bugs that we would like to see fixed for the release
     (probably the RC list in BUGS) and increase their priority on RT

   o Every day, request that developers "claim" on RT any of these bugs that
     they think they can fix

   o After a few days or a week, any remaining bugs are left for the next
     release - if nobody claims them they obviously won't be fixed

   o Create a branch on CVS for creating a release. All code for the stable
     release will come from the list generated by tools/cvsbranch.sh. Exclude
     any modules with bugs that were not "claimed". Markus
     (read: http://www.loria.fr/~molli/cvs/doc/cvs_5.html#SEC49 )

     [Note: due to confusions arising from branches, we should avoid that
            for 5.1]
     
   o The only commits to the release branch are *minor* bug fixes (not
     necessarily only those claimed) - other developments are committed to
     the MAIN branch. Any *major* bug fixes require consensus from the
     developers and/or approval from Markus to commit to the release branch.
     
   o To submit a bug fix to the release branch: 
     
     o Check out the release branch from CVS into a NEW directory if this has
       not been done yet.
       
     o Tag the files you will change before you edit them
     
     o Make the changes to the source code that will fix the bug
     
     o Commit the bug fix to the release branch
     
     o Merge the bug fix to the MAIN trunk
       
     o All developers who subscribe to the commit list (should
       list both names and email addresses) should take responsibility for
       monitoring the code committed to the release branch.
     
   o Once all claimed bugs are fixed, tag this branch as pre release 1
     and start the pretest phase.
     For that run within the existing branch version:
       cvs tag -c <tagname>

1. Add disclaimer to all mails to be sent to the pre-testers:

   ------------------
   GRASS 5 beta DISCLAIMER: WARNING
   This pre-release of GRASS 5 is in alpha-quality only. The
   pre-release is intended to find critical bugs which would
   cause problems in the later official release. All pre-testers
   may submit bug reports and comments immediately to allow
   the new official release to be published as soon as possible.
   Please read the BUGS file to see unresolved bugs.
   Use the bug report form to report bugs:
   http://grass.itc.it/grass/bugtracking/bugreport.html 

   Unless the pre-testing phase isn't finished, no official release
   is possible.
   ------------------

   This displaimer shall lower the expectations and make the users
   recall that they are using beta software not yet announced to be
   stable.

   List of pre-testers:
   See ./pretesters.txt
   (find more!)
   And send them the pretesting_grass.txt file (improvements?)


2. while GRASS_PRE=unstable do

     a) send (new) source/binary tarball to pre-testers
     b) receive comments/bug reports
     c) fix *only* these bugs, no other commits allowed in release branch
     d) if no (more) complaints
          GRASS_PRE=stable
   done

3. Proceed to publishing by publishing the code in the release branch.
   See the sections below for details

4. Fix any bugs reported by users and release a bug-fix version (eg version
   5.0.0 is released, bugs are found and fixed, release version 5.0.1)

5. At some point Markus decides there will be no more releases for this
   version, the release branch is considered dead, and changes are merged into
   the main branch. Note that merges could be made throughout this process to
   the main branch but merging from the main branch to the stable branch is not
   allowed at any time.

6. One of the keys to this scheme is cooperation among the developers.
   Basically the developers have to concentrate on fixing bugs, but those
   who cannot fix bugs can still commit features if they wish. Another key
   is that the developers should ask Markus if their new code can be
   committed to the release branch before committing it, if they
   are not sure if it should or not.

--------------------------------------------------------------

Create source and binary distributions:

0. Create the source code tarball: Markus

   o Check version string:
       src/CMD/VERSION

   o Update Version in NEWS.html

   o Markus:
     - Check if no M/C CVS conflicts have been there before tagging
       (not to forget something)
     - mail to "grass5" to interrupt submitting

     - Tag the new version in the (cleaned) release_branch directory:
         cvs tag -c <tagname>
       e.g.
         cvs tag -c release_DD_MM_20YY_grass5_0_X

     - Check out into a fresh directory with anonymous CVS:
        - mkdir grass5.0.X ; cd grass5.0.0X
        - export CVSROOT=:pserver:grass-guest@intevation.de:/home/grass/grassrepository
        - cvs login
        - cvs -z3 co -r release_DD_MM_20YY_grass5_0_X grass
        - rename 'grass' directory to 'grass5.0.X'

     - Change back to directory of release branch:
        make changelog

       (probably better use
        cvs2cl.pl --follow releasebranch_26_april_2002_5_0_0
       or appropriate release branch)
      
     - polish and add 'Changelog' file to src package 

     - mail to "grass5" to re-allow submitting

     - build source tarball (including the parent directory): 
       Note the file name convention:
        tar cvfz grass-5.0.X_src.tar.gz grass5.0.X

   o Markus:
     Update the PDF-docs on server (needs "htmldoc" tool):
       ftp://ftp.funet.fi/pub/mirrors/ftp.easysw.com/pub/htmldoc/

       gmake5 html/ pdf-docs

     upload result from dist.$ARCH/documents/pdf to GRASS web server
     (grass5/manuals/) remove files then from dist.$ARCH/documents/pdf.

   o Store the source tarball in:
     http://grass.itc.it/grass/grass5/source/
     along with associated files:
          NEWS.html ChangeLog SUBMITTING REQUIREMENTS.html INSTALL

   o update web site to new version (HTML in /cvsweb )
      - index.html
      - grass5/index.html
      - download.html
      - bugtracking/bugreport.html



BINARIES

1. Generally the binaries shall be produced from the published
   source code tarball above. Get this tarball and unpack it in
   a NEW directory.

2. Build GRASS:
   o compile the FFTW library, it is needed for various modules (see
     ../REQUIREMENTS.html where to find it)

   o compile everything, incl NVIZ without PG (note, no ";" to be used):
       CFLAGS=-O2 LDFLAGS="-s" ./configure --without-postgres
       make
     
#   o compile G3D tools
#       gmake5 src.contrib/GMSL/g3d - CURRENTLY NOT STABLE, not required for
#                                     GRASS 5.0.0!

   o compile PostgreSQL modules:
       CFLAGS=-O2 LDFLAGS="-s" ./configure --with-postgres=yes
       make pre-compile
       gmake5 src.garden/grass.postgresql

   o compile PNGDriver (requires "libgd1.8.x" from
     http://www.boutell.com/gd/, usually shipping with Linux distros):
       gmake5 -i src/display/devices/PNGdriver

   o Run again to link the additional modules:
       gmakelinks5
     or 
       gmakelinks5 |wc -l
   
     Should be > 350 modules now.

   o To install into /usr/local/bin (or whereever you directed it) run
       make install-strip

     This will also strip symbols from the executable binaries to reduce the
     binaries size.

   o For r.in.gdal we need "libgdal" which has to be included into the GRASS
     binary package. Finally store "libgdal.1.1.so" in $GISBASE/lib/
     It is highly recommended to get the latest GDAL CVS version:
       export CVSROOT=:pserver:anonymous@cvs.remotesensing.org:/cvsroot
       cvs login
       Password: anonymous
       cvs checkout gdal

       configure --without-python ; make;
       make install
       cp /usr/local/lib/libgdal.1.1.so /usr/local/grass5/lib
       # this copies the libgdal into GRASS binaries

     If above fails, get the precompiled GDAL library:
     - Get Linux version here:
         ftp://gdal.velocet.ca/pub/outgoing/libgdal-linux-grass.tar.gz
         (Note: check "ldd libgdal.1.1.so" dependency, get if required:
         ftp://gdal.velocet.ca/pub/outgoing/libstdc++-libc6.2-2.so.3)
     - Other precompiled libgdal versions:
         http://gdal.velocet.ca/projects/grass/index.html
     - Get GDAL sources at:
         http://www.remotesensing.org/gdal/

   Before packaging, you should test the GRASS now. NVIZ working?
   Bad news to "grass5" list (good as well)!


3. Package the new GRASS binaries with

    make bindist


4. Upload 
     grass5x_y_bin.tar.gz AND grass5install.sh
   to ftp site in Italy (ftp grass.itc.it - store in incoming directory,
   anonymous login). Tell Markus about it after uploading.
   
   Note that when the binaries are created, the size of the resulting
   tar.gz file is stored in the grass5install.sh program. This is done in
   order to check that the download of the binary file was successful.
   Thus both the tar.gz file and the install program need to be uploaded.

--------------------------------------------------------------

Publish the new official GRASS 5 release:

1. Publish it on web site:
   - grass5x_y_bin.tar.gz
   - grass5install.sh

   - grass5x_y_src.tar.gz


2. Tell others about it:
   - related announcement press release at:

   Our GRASS web site: /announces/

   news:comp.infosystems.gis
   http://spatialnews.geocomm.com/submitnews.html (not free any more)
   http://freshmeat.net/projects/grass/?highlight=GRASS
   http://www.linuxapps.com/?page=application&database=current&id=40
   http://www.newsforge.com/submit.pl
   http://osx.macnn.com/ (email to news tips)
   http://www.gis-news.de/  (news@gismngt.de)
   http://www.giscafe.com/   (link: submit material, needs registration)
   http://www.geopoint.de/  (German GIS journal)
   http://www.freegis.org
   http://www.directionsmag.com/pressreleases.php (click on 'Contact Us')
   http://www.gisdevelopment.net (click on 'Submit Press Release')

   ... anywhere else?
