4 Thanks for wanting to contribute. Here are the steps to keep in mind
6 - Check if your contribution is not already part of some package we already use or
8 - Check that no-one else is currently implementing the same stuff.
9 - (If outside Intra2net): Fork the repo.
11 - Develop your code there.
12 - Only add functionality that is relevant for more than just your current project.
13 - document your code (see below), use descriptive names for variables, functions, classes, ...
14 - Run pylint, pep8, pydocstyle and try to minimize complaints.
15 (If code is clearly more easily readable by violating suggestions, then that is ok.)
16 - Create commits for each set of changes with well-formatted messages (see below).
17 - Create unittests for the new functionality you implemented.
18 - Run pylint, pep8, pydocstyle again.
19 - Run unittests using the python version currently shipped with Intra2net systems.
20 All tests must pass (or be skipped)
22 - (If outside Intra2net): Create pull request.
23 - Tell maintainer (christian.herdtweck@intra2net.com) that branch is ready for merge.
24 - Discuss changes with maintainer.
28 Well-formatted doc strings:
29 --------------------------
30 - Every module, class, function, relevant constant or global variable needs a doc string.
31 - Doc strings must appear in line right after function/class declaration or at start of module.
32 For classes and functions/methods, there are 2 options:
33 - Option A: a one-liner with triple """ at start and end without space, e.g.:
34 EG: def set_attribute(self, number):
35 EG: """Set value of class_attribute to given number."""
36 EG: self.attribute = number
37 Only to be used if parameters and returns are clear.
38 - Option B: a multi-liner that describes more details, side-effects (e.g. exceptions raised),
39 params and return types. Needs tripe """ at start and end in separate line, e.g.:
40 EG: def filter_items(input_list, name=None, value=None):
42 EG: Find and return all list items that match given criteria.
44 EG: Searches through all items in list, and returns those that match all of the
45 EG: criteria specified by params. A None-value for params (default) causes
46 EG: criterion to be ignored.
48 EG: :param input_list: List of items to look through
49 EG: :type input_list: list or tuple or other iterable
50 EG: :param str name: Only select items whose .name attribute matches this name
51 EG: :param int value: Only select items whose .value matches this value
52 EG: :returns: List of items matching criteria
54 EG: :raises: ValueError if input is not iterable
56 EG: for item in input_list:
58 - All docstring contents (also that of one-liners) must be (almost) proper sentences
59 with first word capitablied, proper punctuation, etc.
60 - For global variables and constants, doc strings should be in line above the
61 variable or in same line. They must start with "#: ", e.g.:
62 EG: #: Default value for verbosity, only used if user does not give command
63 EG: #: line argument '-v'.
64 EG: DEFAULT_VERBOSITY = 2
65 - Really nice would be sphinx-compatible links e.g. to a :py:func:`test_function`
66 or :py:class:`module.TestClass` or a :py:meth:`TestClass.test_method` or some
67 :py:data:`CONSTANT_NAME`.
68 - pydocstyle, pylint and pep8 usually give hints here, as well.
71 Well-formatted commit messages:
72 -------------------------------
73 - One short summary statement (<= 50 characters) in present tense
74 - First char upper case, no punctuation at end.
75 - Next line must be blank.
76 - Add more details on the commit as required.
77 - Wrap text at 72 characters.
78 - Focus more on the "why" than the "how".
git://developer.intra2net.com / pyi2ncommon / blob