README.coders

This files contains notes to coders who want to contribute to the project

#
# Code Style
#
The code must run under python 3.4->

Aspirationally, write code following the PEP 8 style guide.  
While I dislike some of PEP 8, making it the convention avoids bike shed arguments.
Before check-in you should format the code using

autopep8 --in-place --aggressive --aggressive somefile.py
or 
black somefile.py



#
# Running unittests
#
The unit tests are written using the python unittest framework.  They can be run using
python3 -m unittest discover -b
nosetests
noestests-3.x  (where is is appropriate to your machine)

#
# Running coverage tests
#
pytest --cov=ct ct/test_*
nosetests-3 --with-coverage

#
# Caches/Performance
#
When you are doing performance testing there are 3 caches you need to be aware of

1) ccache:  This can be cleaned by ccache -C
2) cake:    The default is for any caches to be kept in the bin directory.  rm -rf bin 
3) ct-*:    The default cache is supplied by the appdirs module.  
            So on linux that means the XDG user cache directory which defaults to $HOME/.cache/ct.  
                rm -rf ~/.cache/ct
            Note that it obeys the XDG variables.  Alter XDG_CACHE_HOME if you need to move the cache.
            ct-cache-clean will correctly remove the cache as specified by the XDG_CACHE_HOME
            It is possible to override the above by specifying the CTCACHE environment variable.
            CTCACHE=None turns off diskcaching

#
# Gotchas
#
If you encounter

    ValueError: unsupported pickle protocol: 3

its because you are doing python2/3 testing and the pickled cache is in python3 format 
and you are currently testing in python2.  Solution is to remove the ct cache (ct-cache-clean).

#
# Making a release
#
There is now a ct-release script that should do all the following steps

# Zeroth: Make sure all *.rst files have been added to .bumpversion.cfg

# First increase the version number using bumpversion.
# The currently actively developed bumpversion is https://github.com/c4urself/bump2version
# The .bumpversion.cfg has been set to tag and commit (but not push)
bumpversion patch
or
bumpversion minor
or 
bumpversion major

git push
git push --tags

# Based off https://wiki.python.org/moin/TestPyPI
# Note: Using python setup register is not recommended anymore
# https://packaging.python.org/distributing/#uploading-your-project-to-pypi
# Note: You have to create user accounts at pypi and pypitest separately
# You probably wont need to do the twine register since the project already is registered
python setup.py sdist
twine register dist/compiletools-*.tar.gz -r pypitest
twine upload dist/*  -r pypitest

# Test all is well
pip install -i https://testpypi.python.org/pypi compiletools
pip uninstall compiletools

# Rinse and repeat with the live PyPI
twine register dist/compiletools-*.tar.gz -r pypi 
twine upload dist/*  -r pypi 
pip install compiletools