How to contribute:
------------------

Thanks for wanting to contribute. Here are the steps to keep in mind

- Check if your contribution is not already part of some package we already use or
  might as well import.
- Check that no-one else is currently implementing the same stuff.
- (If outside Intra2net): Fork the repo.
- Create a branch.
- Develop your code there.
- Only add functionality that is relevant for more than just your current project.
- document your code (see below), use descriptive names for variables, functions, classes, ...
- Run pylint, pep8, pydocstyle and try to minimize complaints.
  (If code is clearly more easily readable by violating suggestions, then that is ok.)
- Create commits for each set of changes with well-formatted messages (see below).
- Create unittests for the new functionality you implemented.
- Run pylint, pep8, pydocstyle again.
- Run unittests using the python version currently shipped with Intra2net systems.
  All tests must pass (or be skipped)
- Push your branch.
- (If outside Intra2net): Create pull request.
- Tell maintainer (christian.herdtweck@intra2net.com) that branch is ready for merge.
- Discuss changes with maintainer.
- Accept gratitude.


Well-formatted doc strings:
--------------------------
- Every module, class, function, relevant constant or global variable needs a doc string.
- Doc strings must appear in line right after function/class declaration or at start of module.
  For classes and functions/methods, there are 2 options:
- Option A: a one-liner with triple """ at start and end without space, e.g.:
  EG: def set_attribute(self, number):
  EG:     """Set value of class_attribute to given number."""
  EG:     self.attribute = number
  Only to be used if parameters and returns are clear.
- Option B: a multi-liner that describes more details, side-effects (e.g. exceptions raised),
  params and return types. Needs tripe """ at start and end in separate line, e.g.:
  EG:  def filter_items(input_list, name=None, value=None):
  EG:  """
  EG:  Find and return all list items that match given criteria.
  EG:
  EG:  Searches through all items in list, and returns those that match all of the
  EG:  criteria specified by params. A None-value for params (default) causes
  EG:  criterion to be ignored.
  EG:
  EG:  :param input_list: List of items to look through
  EG:  :type input_list: list or tuple or other iterable
  EG:  :param str name: Only select items whose .name attribute matches this name
  EG:  :param int value: Only select items whose .value matches this value
  EG:  :returns: List of items matching criteria
  EG:  :rtype: [item]
  EG:  :raises: ValueError if input is not iterable
  EG:  """
  EG:  for item in input_list:
  EG:      ...
- All docstring contents (also that of one-liners) must be (almost) proper sentences
  with first word capitablied, proper punctuation, etc.
- For global variables and constants, doc strings should be in line above the
  variable or in same line. They must start with "#: ", e.g.:
  EG:  #: Default value for verbosity, only used if user does not give command
  EG:  #: line argument '-v'.
  EG:  DEFAULT_VERBOSITY = 2
- Really nice would be sphinx-compatible links e.g. to a :py:func:`test_function`
  or :py:class:`module.TestClass` or a :py:meth:`TestClass.test_method` or some
  :py:data:`CONSTANT_NAME`.
- pydocstyle, pylint and pep8 usually give hints here, as well.


Well-formatted commit messages:
-------------------------------
- One short summary statement (<= 50 characters) in present tense
- First char upper case, no punctuation at end.
- Next line must be blank.
- Add more details on the commit as required.
- Wrap text at 72 characters.
- Focus more on the "why" than the "how".