Hacking

As we have so far a tight integrated group, we are typically not forking the repository, but cloning it directly. Members are than able to work on the clones. We may change this in case we see need for forks.

Contributing

The project is open source and if you like you can help. Here are some contribution guidelines:

  • we use the Apache 2.0 licence

  • we recommend to use pycharm for editing and utlize the Inspect Code feature regularly on the files you modify and fix the sensible pep8 warnings. Look at other warnings and errors

  • we disallow editing with notepad

  • use .format instead of % in print statements

  • use from __future__ import print_function at the beginning of the file and use print("msg") instead of print msg

  • use class name(object): and not just class name:

  • use Console.error when printing errors if you develop a command for the commandline

  • use Console.ok when printing something that confirms the action is ok. In many cases you may not want o use print, but Console.ok. Please note that Console.ok, takesa string argument.

  • use ConfigDict when reading yaml files. It even allows you to read a yaml file in order, make changes to it and write it back

  • use nosetests and pytest for testing your programs

    An example is provided in tests/test_sample.py:

    nosetests -v --nocapture tests/test_sample.py
    py.test  tests/test_sample.py
    

    you can copy this to tests/test_yourfile.py and then replace in that file the occurrence of _sample with _yourfile

    make sure to create meaningful tests.

  • use RST to write documentation http://sphinx-doc.org/rest.html

  • do not include fancy self tests in the documentation, instead write nosetests

  • we are using https://pypi.python.org/pypi/gitchangelog for creating changelogs automatically. Thus you need to use a prefix in any commit. It includes the type and the user for which the commit is relevant. Examples are:

    chg: usr:    simple changes relevant for users (spelling, ...)
    fix: usr:    major changes for users
    new: usr:    new feature for users
    
    chg: dev:    simple changes relevant for developers (spelling, ...)
    fix: dev:    major changes for developers
    new: dev:    new feature for developers
    
  • use as much python 3 like code but use python 2 for development to also make the code portable on python 2

  • look at http://python-future.org/compatible_idioms.html for tips to make python 2 look more like python 3. Be careful with dicts to make them not inefficient.

  • iteritems:

    import six
    
    d = dict( foo=1, bar=2 )
    
    for k, v in six.iteritems(d):
        print(k, v)
    

PRIORITIZATON

Prioritizations of tasks can be established while using the first line of an issue body. Here you can use a tag such as:

P:1

Where the number behind p identifies the priority. As normal github does not support priority tasks, They can be printed from cloudmesh dev branch, if you use the command:

bin/git-priority,py

We will enhance the tools to print priority lists gradually as needed.

an output will look like:

P N title assignee milestone labels
1 202 cm refresh on/off gregor 2016/03/31 bug, Gregor
999 201 cm cluster fugang priority Fugang

which easily renders in MD. If you are only interested in a particular milestone, you can fgrep for it:

bin/git-priority,py | fgrep priority

An example for sorting and selection is:

bin/git-priority.py | sort -t "|" -k 1 | fgrep priority

Requirements file

There are two primary requirements files:

  • ``requirements-open.txt` are unbounded requirements to be used during development and testing
  • requirements.txt` are the frozen requirements generated by ``pip freeze. This should be updated for every release

Editor

Use PyCharam.

We made bad experience with people using editors other than emacs, vi, and PyCharm. When working on Windows make sure your editor handles newlines properly with git.

Documentation

Creating the documentation with sphinx is easy

pip install -r requirements-doc.txt
make doc

View the documentation

make view

Testing

Tox

We assume that you checked out the newest version from cloudmesh client and base from source and that they are located in:

~/github/cloudmesh/base
~/github/cloudmesh/client

We assume you have tox installed

pip install tox

in the client directory you call tox

cd ~/github/cloudmesh/client
tox

Nosetests

Nose tests can be started with

nosetests

Individual nosetests can be started with (here an example frm test_list.py is used):

pip install -U .; nosetests -v --nocapture  tests/test_list.py:Test_list.test_001

Git

Closing Issues via Commit Messages

To close an issue on github issues, you can use it in your commit messages as follows

git commit -m “Fix problem xyz, fixes #12”

SSH keys

You can get a list of public ssh keys in plain text format by visiting:

https://github.com/{user}.keys

Empty Commits

Commits can be pushed with no code changes by adding –allow-empty:

git commit -m "Big-ass commit" --allow-empty

Styled Git Log

git log --all --graph --pretty=format:'%Cred%h%Creset -%C(auto)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit --date=relative

Tags

Tags are only created by Gregor von Laszewski.

Create a tag. Always use x.y.z

make tag

Remove a tag

make rmtag

Publish on Github

The documentation is only pushed by Gregor von Laszewski.

make publish

Logging

from cloudmesh_client.common.LogUtil import LogUtil

log = LogUtil.get_logger()
log.info("Cloud: " + cloud + ", Arguments: " + str(arguments))