From: Christian Herdtweck <christian.herdtweck@intra2net.com>
Date: Wed, 24 Oct 2018 14:40:22 +0000 (+0200)
Subject: Add CONTRIBUTING guide with rules for contributors
X-Git-Tag: v1.3~3
X-Git-Url: http://developer.intra2net.com/git/?a=commitdiff_plain;h=a72184a14a97d618ea386eecb4445286771fc941;p=pyi2ncommon

Add CONTRIBUTING guide with rules for contributors
---

diff --git a/CONTRIBUTING b/CONTRIBUTING
new file mode 100644
index 0000000..35f0cd5
--- /dev/null
+++ b/CONTRIBUTING
@@ -0,0 +1,78 @@
+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".