How to release
~~~~~~~~~~~~~~
Date: 2015-10-08

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

*PostGIS*

PostGIS release version is composed by POSTGIS_MAJOR_VERSION,
POSTGIS_MINOR_VERSION and POSTGIS_MICRO_VERSION components, all
set in Version.config.

By default only [POSTGIS_MICRO_VERSION] increments between releases.
Starting at PostGIS 2.1 in development  POSTGIS_MICRO_VERSION should have
a "dev" string 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.

*Liblwgeom*

Liblwgeom versioning is composed by by LIBLWGEOM_IFACE_CUR,
LIBLWGEOM_IFACE_AGE and LIBLWGEOM_IFACE_REV; all set and documented
in Version.config.

The liblwgeom versioning represents compatibility of the library
within a PostGIS minor version.

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
- Add the "dev" suffixed version in extensions/upgradeable_versions.mk
  and ensure all the previous released minor versions are listed in it
- Update the README.md to reflect new to be created buildbot badges
	(this should only be needed for trunk release)
- Commit all changes
- If this is a minor or major release (no branch exists):
	   $ base=https://svn.osgeo.org/postgis/
	   $ rev=x.x
	   $ svn copy -m "Branch $rev" $base/trunk $base/branches/$rev

	   Go to: https://debbie.postgis.net and copy last branch version and make new job
	   a) Replace PostGIS_* string params with new version
	   b) Replace repository url with new branch repo url
	   c) Update the PostGIS_trunk by updating the PostGIS_* string params

	   Go to: ​https://trac.osgeo.org/postgis/ edit the matrix to reflect new branch

- Tag branch:  (replace x.x and x.x.x with minor and micro version e.g 2.3, 2.3.1
   $ base=https://svn.osgeo.org/postgis/
   $ brev=x.x
   $ rev=x.x.x
   $ svn copy -m "Tagged release $rev" $base/branches/$brev $base/tags/$rev
- Run: sh make_dist.sh $rev (note, debbie should have already done this,
      and the file will be waiting in postgis.net/stuff.  You might need to wait a few minutes to see it.)
      If impatient check status of job - https://debbie.postgis.net/job/PostGIS_Make_Dist/
- Documentation should also have been built and should be in postgis.net/stuff
  (this sometimes takes sometime so wait 15 minutes)
- Test generated tarball (including extension upgrade)
- Copy tarball, pdf, doc-html.. to http://download.osgeo.org/postgis/ web site and edit postgis.net/source page
- Announce on e-mail
    - postgis-users
    - postgis-devel
    - pgsql-announce (send email just to them, not with other ccs, they reject if others in cc)
    - send note to david at fetter dot org to be included in Weekly news
    - osgeo-discuss
- Update web sites
    - PostGIS News
      - https://git.osgeo.org/gitea/postgis/postgis.net/src/master/_content/posts
       a) create a new Post for current year making sure the page name starts with mm-dd
       b) Update links on https://git.osgeo.org/gitea/postgis/postgis.net/src/master/_content/pages/source.html
       c) commit and wait 5 minutes to see changes on website
    - PostGIS doc release versioned doc - http://postgis.net/documentation/
    - On postgis.net server, change /etc/apache2/postgis.net-common.conf (Versionless URL line )
     Verify the documentation is up to date (might need to change the apach config)
    - Wikipedia
    - Twitter
       This should automatically happen as a result of posting to PostGIS website since Planet PostGIS autotweets.
- Update Trac and make old Milestone as completed
- Push the revision number forward (see Versioning Scheme)
- Remove the "dev" suffixed version from extensions/upgradeable_versions.mk