
This document describes the process of making a new release of xrayutilities.
It is therefore not relevant for users, but for developers and packagers only.

Note: This procedure is intended for use on a Unix operating system.

CHECK EVERYTHING
================

Is everything running fine? perform the tests and run the examples

  # change the version in VERSION
  # update copyright notice in doc/source/conf.py
  pycodestyle xrayutilities
  # allowed output is:
  # xrayutilities/materials/elements.py:36:1: E741 ambiguous variable name 'O'
  # xrayutilities/materials/elements.py:139:1: E741 ambiguous variable name 'I'
  # xrayutilities/math/fit.py:100:80: E501 line too long (100 > 79 characters)
  # xrayutilities/math/fit.py:199:80: E501 line too long (90 > 79 characters)
  # xrayutilities/math/fit.py:273:80: E501 line too long (90 > 79 characters)
  # xrayutilities/math/fit.py:314:80: E501 line too long (90 > 79 characters)
  python2 setup.py test
  python3 setup.py test
  # optionally check the coverage
  # also see http://coverage.readthedocs.io/en/coverage-4.2/subprocess.html
  export COVERAGE_PROCESS_START=.coveragerc
  coverage run --source xrayutilities setup.py test
  coverage combine
  coverage html

run the examples

UPDATE DOCUMENTATION
====================

to build the documentation from scratch first one needs to rebuild the API
documentation sources (which is done from the installed module, so make sure
you have the latest version installed!)

  sphinx-apidoc -f -o doc/source xrayutilities

In the root directory of the package execute the following to rebuild the
documentation pdf. You will need sphinx, numpydoc and rst2pdf.

  python setup.py build build_doc -b pdf
  cd build/sphinx/pdf; pdftk xrayutilities.pdf output ../../../xrayutilities.pdf ; cd ../../..

Or generate a texinfo file using

    python setup.py build_doc -b texinfo
    cd build/sphinx/texinfo; make

PACKAGING
=========

create a tarball for redistribution of xrayutilities without the use of git

  python setup.py sdist

creates a tarball in the directory dist, which contains everything needed for
the installation of xrayutilities

This tarball should be uploaded to sourceforge and PyPI.

To build a executable installer for Microsoft windows run

  python setup.py bdist_wininst

on a windows machine.
If not done previously you need to build the extenstion modules using

  python setup.py build -c <compiler_name>

The compiler name can be omitted if the default is working.

For up to date Python installations you should use Visual Studio 2015.
To perform the installation or build a installer package perform the
following steps:
 * open an administrator shell (or winpython command prompt)
 * (optional) execute: 'set DISTUTILS_USE_SDK=1'
 * (optional) execute: 'setenv /x64 /release' (use /x86 for a 32-bit build)
 * compile with: 'python setup.py build'. one might need to use
   '--without-openmp' option for building.
 * build binaries with 'python setup.py bdist_wininst bdist_wheel' 
 * install package locally 'python setup.py install'
 * use 'python setup.py test' to test your installation

GIT tagging
-----------

tag the version in the GIT repository and publish the version tag to Github

  git tag -a vX -m "version X"
  git push origin vX

UPDATE WEBPAGE
==============

rebuild the html documents and upload them to the sourceforge webserver
to have the correct style the style file needs to patched

  python setup.py build_doc -b html
  patch -p0 < doc/webpage.patch
  # in case its needed, update the patch with
  # diff -Naur build/sphinx/html/index.html.orig build/sphinx/html/index.html > doc/webpage.patch

to upload new web-documentation connect to the sourceforge server via:

  sftp://USERNAME@web.sourceforge.net
  /home/project-web/xrayutilities/htdocs

files on sourceforge can be moved/archived using

sftp://USERNAME@frs.sourceforge.net/home/frs/project/x/xr/xrayutilities

however, upon such a move the download statistics are lost.

UPDATE PyPI PACKAGE
===================

Upload new version to the Python package index by

  twine upload dist/xrayutilities-VERSION.tar.gz

On a windows machine run

  twine upload --config-file PATH_TO_pypirc dist/*

or download the artifacts from AppVeyor and publish them to PyPI using twine

Github release and mailing list anouncement
===========================================

Finally announce the new release on Github (which will also upload the new
version to Sourceforge) and drop a mail to the user mailinglist:
xrayutilities-users@lists.sourceforge.net
