Updated CONTRIBUTING.md with all existing python/robot standards.
Change-Id: I19e1c158889a891fe0d0620adb779df58c2a9e51
Signed-off-by: Michael Walsh <micwalsh@us.ibm.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
old mode 100755
new mode 100644
index 9e93f67..bd1e0e9
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,40 +5,37 @@
Submitting changes via Gerrit server
------------------------------------
-- Reference [openbmc docs](https://github.com/openbmc/docs/blob/master/contributing.md#submitting-changes-via-gerrit-server)
+- Reference [OpenBMC docs](https://github.com/openbmc/docs/blob/master/contributing.md#submitting-changes-via-gerrit-server)
Robot Coding Guidelines
-----------------------
- For this project, we will write Robot keyword definitions in either Robot
- or python. Robot code should be quite simple. Therefore, if algorithm
- in question is the least bit complex, please write it in python.
+ or Python. Robot code should be quite simple. Therefore, if the algorithm
+ in question is the least bit complex, please write it in Python.
+- Observe a maximum line length of 79 characters.
+- Avoid trailing space at the end of any line of Robot code.
+- Avoid the use of tabs.
- Robot supports delimiting cells with either two or more spaces or with a
pipe symbol (e.g. "\|"). Our team has chosen to use spaces rather than the
- pipe character. Make sure all space delimiters in robot code are the
+ pipe character. Make sure all space delimiters in Robot code are the
**minimum** of two spaces. There may be some exceptions to this rule.
Exceptions to two-space delimiter rule:
-
- When you wish to line up resource, library or variable values:
-
```
Library Lib1
Resource Resource1
*** Variables ***
${var1} ${EMPTY}
```
-
- When you wish to line up fields for test templates:
-
```
[Template] Set System LED State
# LED Name LED State
power On
power Off
```
-
- When you wish to indent if/else or loop bodies for visual effect:
-
```
Run Keyword If '${this}' == '${that}'
... Log Bla, bla...
@@ -46,4 +43,282 @@
... Run Keywords Key1 parms
... AND Key2 parms
```
-
+- When you define or call a Robot keyword, Robot pays no attention to spaces,
+ underscores or case. However, our team will observe the following
+ conventions in both our definitions and our calls:
+ - Separate words with single spaces.
+ - Capitalize the first character of each word.
+ - Capitalize all characters in any word that is an acronym (e.g. JSON, BMC,
+ etc).
+
+ Examples:
+ ```
+ *** Keywords ***
+
+ This Is Correct
+
+ # This keyword name is correct.
+
+ this_is_incorrect
+
+ # This keyword name is incorrect because of 1) the
+ # underscores instead of spaces and 2) the failure to
+ # capitalize each word in the keyword.
+
+ soisthis
+
+ # This keyword name is incorrect because of 1) a failure to
+ # separate words with spaces and 2) a failure to capitalize
+ # each word in the keyword.
+
+ BMC Is An Acronym
+
+ # This keyword name is correct. Note that "BMC" is an
+ # acronym and as such is entirely uppercase.
+ ```
+- Documentation strings:
+ - Each documentation string should be phrased as an **English command**.
+ Punctuate it correctly with the first word capitalized and a period at
+ the end.
+
+ Correct example:
+ ```
+ Boot BMC
+ [Documentation] Boot the BMC.
+ ```
+ Incorrect example:
+ ```
+ Boot BMC
+ [Documentation] This keyword boots the BMC.
+
+ # The doc string above is not phrased as a command.
+ ```
+ - Doc strings should be just one terse, descriptive sentence.
+ Remember that this doc string shows up in the HTML log file. Put
+ additional commentary below in standard comment lines.
+
+ Correct example:
+ ```
+ Stop SOL Console Logging
+
+ [Documentation] Stop system console logging and return log output.
+ ```
+ Incorrect example:
+ ```
+ Stop SOL Console Logging
+
+ [Documentation] Stop system console logging. If there are multiple
+ ... system console processes, they will all be
+ ... stopped. If there is no existing log file this
+ ... keyword will return an error message to that
+ ... effect (and write that message to targ_file_path,
+ ... if specified). NOTE: This keyword will not fail
+ ... if there is no running system console process.
+
+ # This doc string is way too long.
+ ```
+- Tags:
+ - Create a tag for every test case with a tag name that mirrors the test case
+ name as follows:
+ ```
+ Create Intermediate File
+
+ [Tags] Create_Intermediate_File
+ ```
+- General variable naming conventions:
+ - Variable names should be lower case with few exceptions:
+ - Environment variables should be all upper case.
+ - Variables intended to be set by Robot -v parameters may be all
+ upper case.
+ - Words within a variable name should be separated by underscores:
+
+ Correct examples:
+ ```
+ ${host_name}
+ ${program_pid}
+ ```
+ Incorrect examples:
+ ```
+ ${HostName}
+ ${ProgramPid}
+ ```
+- Special variable naming conventions.
+
+ For certain very commonly used kinds of variables, please observe these
+ conventions in order to achieve consistency throughout the code.
+
+ - hosts
+
+ When a variable is intended to contain **either** an IP address **or**
+ a host name (either long or short), please give it a suffix of "_host".
+
+ Examples:
+ ```
+ openbmc_host
+ os_host
+ pdu_host
+ openbmc_serial_host
+ ```
+ - host names
+
+ For host names (long or short, e.g. "bmc1" or "bmc1.ibm.com"), use a
+ suffix of _host_name.
+
+ Examples:
+ ```
+ openbmc_host_name
+ os_host_name
+ pdu_host_name
+ openbmc_serial_host_name
+ ```
+ - Short host names
+
+ For short host names (e.g. "bmc1"), use a suffix of _host_short_name.
+
+ Examples:
+ ```
+ openbmc_host_short_name
+ os_host_short_name
+ pdu_host_short_name
+ openbmc_serial_host_short_name
+ ```
+ - IP addresses
+
+ For IP addresses, use a suffix of _ip.
+
+ Example:
+ ```
+ openbmc_ip
+ os_ip
+ pdu_ip
+ openbmc_serial_ip
+ ```
+- Files and directories:
+ - Files:
+ - If your variable is to contain only the file's name, use a suffix
+ of _file_name.
+
+ Examples:
+ ```
+ ffdc_file_name = "bmc1.170428.120200.ffdc"
+ ```
+ - If your variable is to contain the path to a file, use a suffix of
+ _file_path. Bear in mind that a file path can be relative or
+ absolute so that should not be a consideration in whether to use
+ the "_file_path" suffix.
+
+ Examples:
+ ```
+ status_file_path = "bmc1.170428.120200.status"
+ status_file_path = "subdir/bmc1.170428.120200.status"
+ status_file_path = "./bmc1.170428.120200.status"
+ status_file_path = "../bmc1.170428.120200.status"
+ status_file_path = "/home/user1/status/bmc1.170428.120200.status"
+ ```
+ To re-iterate, it doesn't matter whether the contents of the
+ variable are a relative or absolute path (as shown in the
+ examples above). A file path is simply a value with enough
+ information in it for the program to find the file.
+
+ - If the variable **must** contain an absolute path (which should be
+ the rare case), use a suffix _abs_file_path.
+
+ - Directories:
+ - Directory variables should follow the same conventions as file
+ variables.
+
+ - If your variable is to contain only the directory's name, use a
+ suffix of _dir_name.
+
+ Example:
+ ```
+ ffdc_dir_name = "ffdc"
+ ```
+ - If your variable is to contain the path to a directory, use a
+ suffix of _dir_path. Bear in mind that a dir path can be
+ relative or absolute so that should not be a consideration in
+ whether to use _dir_path.
+
+ Examples:
+ ```
+ status_dir_path = "status/"
+ status_dir_path = "subdir/status"
+ status_dir_path = "./status/"
+ status_dir_path = "../status/"
+ status_dir_path = "/home/user1/status/"
+ ```
+ To re-iterate, it doesn't matter whether the contents of
+ the variable are a relative or absolute path (as shown in
+ the examples above). A dir path is simply a value with
+ enough information in it for the program to find the
+ directory.
+
+ - If the variable **must** contain an absolute path (which
+ should be the rare case), use a suffix _abs_dir_path.
+ - IMPORTANT: As a programming convention, do pre-
+ processing on all dir_path variables to ensure that they
+ contain a trailing slash. If we follow that convention
+ religiously, that when changes are made in other parts of
+ the program, the programmer can count on the value having
+ a trailing slash. Therefore they can safely do this kind
+ of thing:
+ ```
+ my_file_path = my_dir_path + my_file_name
+ ```
+- Traditional comments (i.e. using the hashtag style comments)
+ - Please leave one space following the hashtag.
+ ```
+ #wrong
+
+ # Right
+ ```
+ - Please use proper English punction:
+ - Capitalize the first word in the sentence or phrase.
+ - End sentences (or stand-alone phrases) with a period.
+
+ - Do not keep commented out code in your program. Instead, remove it
+ entirely.
+
+Python Coding Guidelines
+-----------------------
+- Run pep8 on all Python files and correct errors.
+
+ Example as run from a Linux command line:
+ ```
+ pep8 my_pgm.py
+
+ my_pgm.py:41:1: E302 expected 2 blank lines, found 1
+ my_pgm.py:58:52: W291 trailing whitespace
+ ```
+- Include doc strings in every function and follow the guidelines in
+ https://www.python.org/dev/peps/pep-0257/.
+
+ Example:
+ ```
+ r"""
+ Return the function name associated with the indicated stack frame.
+
+ Description of argument(s):
+ stack_frame_ix The index of the stack frame whose
+ function name should be returned. If
+ the caller does not specify a value,
+ this function will set the value to 1
+ which is the index of the caller's
+ stack frame. If the caller is the
+ wrapper function "print_func_name",
+ this function will bump it up by 1.
+ """
+ ```
+- As shown in the prior example, if your function has any arguments, include
+ a "Description of argument(s)" section. This effectively serves as the
+ help text for anyone wanting to use or understand your function. Include
+ real data examples wherever possible and applicable.
+- Function definitions:
+ - Put each function parameter on its own line:
+ ```
+ def func1(parm1,
+
+ parm2):
+ ```
+- Do not keep commented out code in your program. Instead, remove it
+ entirely.