Release Packaging

The following are step by step instructions on how to package a release.

Building the Release Packages

Source Code

Step 1

Make sure the source builds and works locally, and the docs build with no errors

Step 2

Make sure the source passes all OGC CITE tests (see OGC-CITE-Compliance for instructions) and unit tests (paver test)

Step 3

Create a release tag against master:

* update desired branch with `x.y.z` in the following files:
 * `VERSION.txt`
 * `pycsw/__init__.py:__version__`
 * `etc/dist/opensuse/python-pycsw.spec` <-- only if this is a final release
 * `etc/dist/osgeolive/install_pycsw.sh` <-- only if this is a final release
 * `etc/dist/debian/changelog` <-- only if this is a final release
* commit the above updates:

```
# in branch master
git commit -am 'update release version'
git push origin master # or branch if releasing from a branch
```

* in the `pycsw.org` repository, update:
 * `docs/index.md` <-- only if this is a final release
 * `download/index.md` to set the current release URL to http://download.osgeo.org/pycsw-x.y.z.tar.gz and http://download.osgeo.org/pycsw-x.y.z.zip

```
# in pycsw.org repository
git commit -am 'update release version'
git push origin gh-pages
```

Release tags are in the format `x.y.z`

If releasing from master:

```
git tag -a x.y.z -m 'tagging x.y.z'
git push --tags
```

If releasing from a branch:

```
git checkout x.y
git tag -a x.y.z -m 'tagging x.y.z'
git push --tags
```

Step 4

Export the package:

```
git archive --format=tar --prefix=pycsw-x.y.z/ x.y.z | (cd /tmp/ && tar xf -)
cd /tmp/pycsw-x.y.z/
```

Step 5

Make the docs locally for the distribution and generate tester/index.html:

paver refresh_docs
paver gen_tests_html

Step 6

Package the distribution:

cd ..
tar cf pycsw-x.y.z.tar pycsw-x.y.z
gzip pycsw-x.y.z.tar
zip -r pycsw-x.y.z.zip pycsw-x.y.z

Step 7

Copy pycsw-x.y.z.tar.gz and pycsw-x.y.z.zip to the download area on http://download.osgeo.org/

scp pycsw-x.y.z.tar.gz pycsw-x.y.z.zip [email protected]:/osgeo/download/pycsw

Step 8

Add the x.y.z documentation to readthedocs.org

• go to https://readthedocs.org/projects/pycsw/
• under 'Build a version', select 'latest' and click 'Build'
• this will cause readthedocs.org to sync release tags, new version will appear
• go to https://readthedocs.org/dashboard/pycsw/versions/
• find x.y.z
• click 'Active' and ensure visibility is set to 'Public'
• click 'Submit'

Step 9

Create a release branch if this is major release.

git branch x.y
git push origin x.y

Step 10

If applicable (for final releases only, not beta or rc releases), update master with the development version to x.y-dev in the following files:

• VERSION.txt
• pycsw/__init__.py:__version__

...and then git push origin master

Step 11

If major release:

• in pycsw.org repository branch:

• create development/announce/x.y.z.md by pasting release announcement

• git add development/announce/x.y.z.md

• ref new page in development/announce/index.md

• vi development/announce/index.md
• git commit -m 'add release announcement page' development/
• git push origin gh-pages

Email announcement to:

• pycsw-devel
• OSGeo-discuss <-- only for final releases
• OSGeo-announce <-- only for final releases
• freegis-list <-- only for final releases
• Twitter
• Google+

Message Template

Subject: pycsw x.y.z released

The pycsw team announces the release of pycsw x.y.z. 

[High level overview of release]

pycsw is an OGC CSW server implementation written in Python.  pycsw implements clause 10 (HTTP protocol binding (Catalogue Services for 
the Web, CSW)) of the OpenGIS Catalogue Service Implementation Specification, version 2.0.2.

pycsw allows for the publishing and discovery of geospatial metadata.  Existing repositories of geospatial metadata can be exposed via  OGC:CSW 
2.0.2.  pycsw is Open Source, released under an MIT license, and runs on all major platforms (Windows, Linux, Mac OS X).

Source and binary downloads:
----------------------------

The source code is available at:

http://pycsw.org/download.html


Version x.y.z (YYYY-MM-DD):
---------------------------

[Bulleted list of enhancements / bug fixes]


Testers and developers are welcome.

The pycsw developer team.

http://pycsw.org/

Step 12

Update OSGeo-Live (for final releases only, not beta or rc releases):

• update pycsw files in http://trac.osgeo.org/osgeo/browser/livedvd/gisvm/trunk as appropriate:
• http://trac.osgeo.org/osgeo/browser/livedvd/gisvm/trunk/bin/install_pycsw.sh
• http://trac.osgeo.org/osgeo/browser/livedvd/gisvm/trunk/doc/en/overview/pycsw_overview.rst (images if required)
• http://trac.osgeo.org/osgeo/browser/livedvd/gisvm/trunk/doc/en/quickstart/pycsw_quickstart.rst (images if required)

Step 13

Update openSUSE packages (for final releases only, not beta or rc releases):

• Login to Open Build Service
• Branch the pycsw package from Application:Geo repository
• Replace the package spec file with the updated etc/dist/opensuse/pycsw.spec
• Update the changes file
• Upload the latest pycsw-x.y.z.tar.gz file
• Wait for the build results and make corrections to etc/dist/opensuse/pycsw.spec in case of failures or warnings.
• If successful submit a pull request to Application:Geo

Step 14

Update Ubuntu packages (for final releases only, not beta or rc releases):

• Install packaging tools:

sudo apt-get install devscripts build-essential fakeroot debhelper gnupg pbuilder dh-make

• Create account and login to Launchpad
• Setup your account with OpenPGP and SSH keys in order to be able to sign off your changes.
• Download the latest source, rename (as per Debian rules) and unpack:

wget http://download.osgeo.org/pycsw/pycsw-x.y.z.tar.gz
mv pycsw-x.y.z.tar.gz pycsw_x.y.z.orig.tar.gz
tar zxvf pycsw_x.y.z.orig.tar.gz

• Update the debian installation files in etc/dist/debian using your name and e-mail address as published in OpenPGP key above or the packaging will fail.
• Move debian folder to top level:

cd pycsw-x.y.z
mv etc/dist/debian ./

• Execute debuild to create the package and sign off the .changes and .dsc files

$ debuild -S

• Build locally to make sure everything works before publishing the package (optional but recommended):

cd ..
sudo pbuilder --build pycsw_x.y.z-0.dsc

• Upload the sources to Launchpad with:

dput ppa:pycsw/devel pycsw_x.y.z-0.changes

• Wait for package to build successfully
• After testing the created deb files, contact UbuntuGIS team to pull the new pycsw packages to official repository.

Step 15

Upload to PyPi (for final releases)

git checkout x.y.z
python setup.py sdist upload

• Note: for alpha/beta/rc releases, use TestPyPI

git checkout x.y.z-beta1
# if package is not registered
python setup.py sdist register -r https://testpypi.python.org/pypi  # (testpypi gets wiped clean regularly)
python setup.py sdist upload -r https://testpypi.python.org/pypi

Step 16

Update https://en.wikipedia.org/wiki/Pycsw (for final releases)

• release information
• history (for major and minor releases)
• new features/enhancements