Commit | Line | Data |
---|---|---|
a72184a1 CH |
1 | How to contribute: |
2 | ------------------ | |
3 | ||
4 | Thanks for wanting to contribute. Here are the steps to keep in mind | |
5 | ||
6 | - Check if your contribution is not already part of some package we already use or | |
7 | might as well import. | |
8 | - Check that no-one else is currently implementing the same stuff. | |
9 | - (If outside Intra2net): Fork the repo. | |
10 | - Create a branch. | |
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) | |
21 | - Push your branch. | |
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. | |
25 | - Accept gratitude. | |
26 | ||
27 | ||
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): | |
41 | EG: """ | |
42 | EG: Find and return all list items that match given criteria. | |
43 | EG: | |
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. | |
47 | EG: | |
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 | |
53 | EG: :rtype: [item] | |
54 | EG: :raises: ValueError if input is not iterable | |
55 | EG: """ | |
56 | EG: for item in input_list: | |
57 | EG: ... | |
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. | |
69 | ||
70 | ||
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". |