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 (py.test -k "not harvesting")

Step 3

Create a release tag against master:

* update desired branch with `x.y.z` in the following files:
 * `VERSION.txt`
* commit the above updates:

```bash
# in branch master
git commit -m 'update release version' VERSION.txt
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 https://download.osgeo.org/pycsw-x.y.z.tar.gz and https://download.osgeo.org/pycsw-x.y.z.zip

```bash
# in pycsw.org repository
git commit -m 'update release version' docs/index.md download/index.md
git push origin gh-pages
```

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

If releasing from master:

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

If releasing from a branch:

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

Step 4

Export the package:

```bash
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:

make clean
make 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 https://download.osgeo.org/pycsw

scp pycsw-x.y.z.tar.gz pycsw-x.y.z.zip $OSGEO_USERID@download.osgeo.org:/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/projects/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

...and then git push origin master

Step 11

Upload to PyPi (for final releases)

git checkout x.y.z
python setup.py sdist bdist_wheel --universal
twine upload dist/*.gz dist/*.whl

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

git checkout x.y.z-beta1
# if package is not registered
python setup.py sdist upload -r https://test.pypi.org/legacy/

Step 12

If major release:

in pycsw.org repository gh-pages 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
Twitter

Message Template


Subject: pycsw x.y.z released

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

[High level overview of release]

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

The source code is available at:

https://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.

https://pycsw.org

Note: for announcing to new communities, add:

pycsw is an OARec and OGC CSW server implementation written in Python.

pycsw fully implements the OGC API - Records and OpenGIS Catalogue Service Implementation Specification (Catalogue Service for the Web). Initial development started in 2010 (more formally announced in 2011). The project is certified OGC Compliant, and is an OGC Reference Implementation.  Since 2015, pycsw is an official OSGeo Project.

pycsw allows for the publishing and discovery of [[geospatial]] metadata via numerous APIs (OARec, CSW 2/CSW 3, OpenSearch, OAI-PMH, SRU). Existing repositories of geospatial metadata can also be exposed, providing a standards-based metadata and catalogue component of spatial data infrastructures.

pycsw is Open Source, released under an MIT license, and runs on all major platforms (Windows, Linux, Mac OS X).

Step 13

Create a release on GitHub.

go to https://github.com/geopython/pycsw/releases
click 'Draft a new release'
under 'Tag Version' add the relevant release tag (x.y.z)
release title should be x.y.z
release description should be a copy/paste of the release message template
click 'Publish release'

Step 14

Refresh Zenodo/DOI

Go to https://zenodo.org/account/settings/
Click "Sync now"
See newly minted DOI based on new pycsw version
update pycsw README
- click on "Get the DOI badge!"
- copy the Markdown
- update README.md
- git commit -m 'update DOI' README.md && git push origin master