.. _release:
.. role:: strike

************************
PySAL Release Management
************************


Preparing a release
===================

One individual developer will be assigned as the release manager and will be
responsible for building and testing the releases.

Pre-Build Activities
--------------------

Prior to the build, there are a number of actions to take. 

     * ensure all tests pass
     * update the change log: use svn2cl to generate the entire project history. Then prepend just the most important changes to the file CHANGELOG.txt.
     * update THANKS.txt 
     * update README.txt 
     * update setup.py to add new modules or remove old ones, and to bump
       version
     * prior to the Tag and final docs build, bump the docs version from x.xdev
       to x.x by editing doc/source/conf.py in two places.
     * create a tag X.0::

	svn copy https://pysal.googlecode.com/svn/trunk \
        https://pysal.googlecode.com/svn/tags/X.0 -m "Release X.0"

     * cd into the new tag directory and build the LaTeX and HTML documentation 
     * Build release for X.0 out of tag X.0 following instructions below

Post-build Activities
-----------------------

  * bump the trunk up to version X.1 by editing `version.py`
  * update the release on http://pypi.python.org:
     * go to http://pypi.python.org/pypi?:action=submit_form
     * pick option 2 to upload the PKG-INFO from top level pysal directory in a release tarball
  * upload releases and docs to code.google.com/p/pysal/downloads
  * edit documentation links on http://code.google.com/p/pysal/ (which as of 1.1 will be the landing page for pysal.org)
  * after the Tag and final docs build, bump the docs version from x.x to x.x+1dev by editing doc/source/conf.py in two places.
  * create new release directory on documentation server
  * copy the new HTML docs to the doc server 
  * :strike:`edit cronjob on peloton to rsync to new release directory`
  * draft release announcement, ensuring docs link point to pysal.geodacenter.org
  * write and distribute the press release on geodacenter.asu.edu, openspace-list, and pysal.org

Building the release
====================

A clean checkout of the trunk should be done on each machine used to build the
release, after the Tag.

Source Distributions
--------------------

As of version 1.3.0, PySAL uses the new Distribute setuptools package.
Distribute offers several advantages over Setuptools:

 * Distribute is a drop-in replacement for setuptools
 * The code is actively maintained, and has over 10 committers.
 * Distribute offers Python 3 support!

To prepare your development environment, follow the instructions at http://packages.python.org/distribute/index.html
The abridged version is to install Distribute::

  pip install distribute

The specification of files and folders to include in all PySAL 
distributions is handled in setup.py :strike:`and MANIFEST.in`. To build a new source package, run::

  python setup.py sdist  

to generate a default source distribution for the build platform (tar.gz on OSX
and Linux, zip on Windows).  A good reference is
http://docs.python.org/distutils/sourcedist.html

Binary Installers for Windows 
-----------------------------

Making a Windows binary installer for XP or 7 should be done on a Windows XP machine.
To build an installer, run:: 

   $ python setup.py bdist_wininst
   
You may also build a Microsoft Installer formatted MSI, which is
prettier but allows the user to install the package in the wrong place. For a
look at that, run:

   $ python setup.py bdist --formats=msi


Binary Installer for OS X 
--------------------------

To make a Mac OS X graphical installer, first install 'bdist_mpkg' from the
Python Package Index. We recommend downloading the source code and using the
included setup.py file to install. Note that you can install multiple versions
of bdist_mpkg, so be sure you know which one you're calling, and which Python it
is associated with. For instance, below we include edits to alter the .mpkg
produced by bdist_mpkg so that PySAL will be installed in the Current version of
Python in the Python Frameworks (i.e. /Library/Frameworks/Python.framework/ ...
). That includes any or most Python distributions not included by Apple, such as
those from python.org and Enthought.

If you were targeting just one of those distributions, EPD for example, you
could forego our edits below by installing a version of bdist_mpkg using the EPD
Python executable. Likewise, if you're only interested to direct the installer
to Python 2.6.6 distributed by python.org, you'd use the bdist_mpkg built by
that executable, and forego the edits below. The same will hold true for other
versions of Python, such as Python2.7 or 3.2., or for Apple-installed Python
located at /usr/bin/python.

After you install 'bdist_mpkg', run ::

    $ bdist_mpkg setup.py build 

which builds the .mpkg/ package installer in the dist/ directory.
*The .mpkg/ will need to be modified to install pysal to the correct
location.* Replace wildcards below with actual filenames. 

  * Edit pysal*.mpkg/Contents/Info.plist, replacing the path under *IFRequirementDicts* with a generic System path such as /Library/Frameworks/Python.framework/Versions/Current/lib/python2.6/site-packages.  This will check that directory exists before installing. Note that Version/Current/lib/python2.6 is a work-around to support both system python and EPD. 

  * Next, find and edit pysal*.mpkg/Contents/Packages/pysal*.pkg/Contents/Info.plist. Change the value after *IFPkgFlagDefaultLocation* to point to /Library/Frameworks/Python.framework/Versions/Current/lib/python2.6/site-packages.

  * Finally, convert the .mpkg/ into a disk image suitable for redistribution by running the command::
 
    $ hdiutil create -fs HFS+ -srcfolder <pysal*>.mpkg/ <pysal*>.dmg


Post-release SVN Changes
========================

Two-dot versions of PySAL are released twice a year. Using the example of
release X.0, we outline plans for updating the repository and bug fixes here.

Development on X.1 happens in trunk. Code in tag X.0 is never changed.  Bugs in
X.0 that are reported by users or developers are fixed in branch X.0 and in
trunk, if relevant. It could be that trunk had moved on so that the bug is no
longer in the trunk code (functionality may have been dropped or refactored for
example).

In the event that bug fixes are substantial between X.0 and the release of X.1,
we could do a release out of branch X.0. This would be tagged as X.0.X. Since
it is a tag, code in there never gets changed, but bug fixes in the X.0.x
series continue to be made in branch X.0.

So to summarize our major versions two-dot:  X.0, X.1, X.2, X.3, etc. These are
released every six months at the end of a release cycle. Bug fix releases for a
major release are three-dot: X.0.1, X.0.2, etc,  and are released during a
release cycle.

Developers wanting to explore major new initiatives are encouraged to make
experimental branches for that work and not use trunk.
