Development Workflows

Here we have a collection of gazelib development conventions and workflows. If the convention changes, please update to avoid conflicts.

Use git

To develop, clone the repository from GitHub:

$ git clone https://github.com/infant-cognition-tampere/gazelib

Make changes to files, add them to commit, and do commit:

(edit README.rst)
$ git add README.rst
$ git commit -m "Improved documentation"

List files that are not added or not committed:

$ git status

Push local commits to GitHub:

$ git push

Ignore some files by editing .gitignore:

$ nano .gitignore

Use conda

Why? First, for compability testing i.e. to ensure that gazelib requires only the packages that are installed in the environment. Second, to conveniently prevent global installation of gazelib's requirements.

Create new conda environment

$ conda create --name gazepy27 python=2 numpy scipy nose-cov

Activate environment

$ source activate gazepy27
(do testing, compile docs, etc)

Deactivate environment

$ source deactivate

Testing with nose

We test for both python 2 and python 3. Run:

$ make testpy2
$ make testpy3

The commands create a conda environment, install everything and run tests. The See Makefile for all available unit testing options, including faster but not so complete options.

Validate reStructuredText .rst

Validate README.rst at rst.ninjs.org/.

Version release

1. Create a release branch from develop: $ git checkout -b release-1.2.3.
2. Change version string in gazelib/package.py. This is automatically used in setup.py.
3. Change version string in docs/source/conf.py.
4. Run tests. See Testing.
5. Update documentation. See Compile documentation.
6. Git commit: $ git commit --all -m "v1.2.3 release"
7. Merge to master: $ git checkout master and $ git merge --no-ff release-1.2.3 -m 'Merge release'
8. Create a signed tag: $ git tag -a 1.2.3 -m "v1.2.3"
9. Push commits and tags: $ git push && git push --tags
10. Publish to PyPI. See Publishing to PyPI.
11. Switch back to develop to avoid accidentally committing to master: $ git checkout develop
12. Merge to develop: $ git merge --no-ff release-1.2.3 -m 'Merge release'
13. Remove the obsolete release branch: $ git branch -d release-1.2.3

See also a successful Git branching model.

Publishing to PyPI

Follow python packaging instructions:

1. Clean your build to avoid obsolete files: rm -rf build/ dist/

2. Create an unpacked sdist: $ python setup.py sdist

3. Create a universal wheel: $ python setup.py bdist_wheel --universal

   • If you see invalid command 'bdist_wheel', run $ pip install wheel and try again.

4. If this is the first release, go to PyPI and register the project by filling the package form by uploading gazelib.egg-info/PKG_INFO file.

5. Upload the package with twine:

   1. Sign the dist: $ gpg --detach-sign -a dist/gazelib-1.2.3.tar.gz and $ gpg --detach-sign -a dist/gazelib-1.2.3-py2.py3-none-any.whl
   2. Upload: twine upload dist/gazelib-1.2.3* (will ask your PyPI password)

6. Package published!

Updating the package takes same steps except the registration and uploading PKG_INFO.

Compile documentation

ReadTheDocs.org builds the documentation automatically after push to GitHub. Manage ReadTheDocs build at readthedocs.org/projects/gazelib. However, automatic API documentation that we are using is not run automatically and therefore we have to update the documentation by hand. See update documentation below.

ReadTheDocs requires documents to be compatible with Sphinx. With the following you should be able to install it and setup all stuff needed.

$ pip install sphinx
$ mkdir docs
$ cd docs
$ sphinx-quickstart
$ cd ..
$ sphinx-apidoc -o docs/source gazelib
$ cd docs
$ nano index.rst
$ pip freeze > requirements.txt
$ make html

Update documentation:

$ sphinx-apidoc --force -o docs/source gazelib

At ReadTheDocs, go to Advanced Settings and turn on virtualenv. Requirements file is available at docs/requirements.txt.

The command sphinx-quickstart asked your name. If your name contains non-ASCII letters e.g. Akseli Palén, edit docs/conf.py and turn all instances to unicode strings: 'Akseli Palén' to u'Akseli Palén'. There is instances even near the end of the long file.