postgis/HOWTO_RELEASE

How to release
~~~~~~~~~~~~~~
Date: 2014-05-14

Versioning Scheme
-----------------

Release version is composed by POSTGIS_MAJOR_VERSION, POSTGIS_MINOR_VERSION
and POSTGIS_MICRO_VERSION components.

By default only [POSTGIS_MICRO_VERSION] increments between releases.
Starting at PostGIS 2.1 in development  POSTGIS_MICRO_VERSION should have a dev at the end

[POSTGIS_MINOR_VERSION] is incremented (and MICRO set to 0) when minor
additions have been introduced (one or two functions can be considered
*micro* additions)

[POSTGIS_MAJOR_VERSION] is incremented (and MICRO and MINOR set to 0) when
a dump/reload of existing spatial databases is *REQUIRED* for things
to work or rather *HIGHLY RECOMMENDED* to get new functionalities.

All POSTGIS_MICRO_VERSION that are in branch or trunk should end in dev.
So for example if you just release 2.1.1, then the 2.1 branch should have
POSTGIS_MICRO_VERSION set to 2dev so that the full version is 2.1.2dev.

Requirements
------------

In order to build a release, you will need to build PostGIS and the 
documentation -- that means having the required software:

* For PostGIS:
  - PostgreSQL 
  - GEOS
  - Proj4
  - GDAL (for raster)
  - json-c (for GeoJSON load support)
* For the docs:
  - xsltproc
  - DocBook XSL scripts
  - ImageMagic
  - DbLatex (for PDF)

Release procedure
-----------------

- Re-generate the ChangeLog (make ChangeLog)
- Edit NEWS: set release date and check all notable changes have
  been reported (extract from ChangeLog).
- Edit README.postgis and set release date and version.
- Add release notes in doc/release_notes.xml
- Update Version.config to drop the "dev" suffix
- Commit all changes
- Tag branch:  
   $ base=http://svn.osgeo.org/postgis/
   $ rev=x.x.0
   $ svn copy -m "Tagged release $rev" $base/trunk $base/tags/$rev
- Run: sh make_dist.sh $rev (or use debbie for this)
- Build and test generated tarball (including extension upgrade)
- Copy tarball to web site and edit downloads page
- Announce on e-mail 
    - postgis-users
    - postgis-devel
    - pgsql-announce
    - osgeo-discuss
- Update web sites
    - PostGIS News
      - https://svn.osgeo.org/postgis/web/_content/posts
       a) create a new Post for current year making sure the page name starts with mm-dd
       b) Update links on https://svn.osgeo.org/postgis/web/_content/pages/source.html
       c) commit and wait 5 minutes to see changes on website
    - PostGIS doc release versioned doc - http://postgis.net/documentation/
     (For building pdf, debbie has tagged jobs 
       -- http://debbie.postgis.net:8080 (log in)
       Create new job copy last tag e.g. PostGIS_2.0_tagged_docs to PostGIS_2.1_tagged_docs
       and make appropriate edits and then just run.
       Or just be lazy and bug Regina Obe do this.
    - Wikipedia
    - Twitter (we all love twitter don't we)
- Update Trac and make old Milestone as completed
- Push the revision number forward (see Versioning Scheme)
- Ensure all the previous released minor versions are listed in
  extension/upgradeable_versions.mk including the one you just released