openbmc/openbmc-test-automation/CONTRIBUTING.md

4 work-in-progress, feel free to propose changes.
8 - Reference
9 …ithub.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes-via-gerrit-server-to-openbmc)
10 - Reference
11 …](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes-via-gerrit-server)
15 - Reference
16 …t Messages](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages)
20 - [Redfish Coding Guidelines](docs/redfish_coding_guidelines.md)
24 - For this project, we will write Robot keyword definitions in either Robot or
30 …- [Quit Writing Ugly Robot Code](https://esalagea.wordpress.com/2014/11/24/robot-framework-quit-wr…
31   - [Robot Dos and Don'ts](https://www.slideshare.net/pekkaklarck/robot-framework-dos-and-donts)
33 - Observe a maximum line length of 110 characters.
34 - Avoid trailing space at the end of any line of Robot code.
35 - Avoid the use of tabs.
36 - Robot supports delimiting cells with either two or more spaces or with a pipe
37   symbol (e.g. "\|"). Our team has chosen to use spaces rather than the pipe
39   two spaces. There may be some exceptions to this rule.
41   Exceptions to two-space delimiter rule:
43   - When you wish to line up resource, library or variable values:
50   - When you wish to line up fields for test templates:
57   - When you wish to indent if/else or loop bodies for visual effect:
66 - Use single spaces to make conditions more readable:
80 - When you define or call a Robot keyword, Robot pays no attention to spaces,
84   - Separate words with single spaces.
85   - Capitalize the first character of each word.
86   - Capitalize all characters in any word that is an acronym (e.g. JSON, BMC,
101       # underscores instead of spaces and 2) the failure to
107       # separate words with single spaces and 2) a failure to capitalize
116 - Documentation strings:
118   - Each documentation string should be phrased as an **English command**.
138   - Doc strings should be just one terse, descriptive sentence. Remember that
166 - Tags:
168   - Create a tag for every test suite with a tag name that represents the suite
179   - Create a tag for every test case with a tag name that mirrors the test case
188 - Description of argument(s):
190   - As shown in the following example, if your keyword has any arguments,
194     2 spaces between the argument name and the description. Align all
214     - Put parentheses around your examples. Leave one space prior to the left
216     - Use "e.g." (which effectively means "for example") to set introduce your
218     - Quote string examples.
219     - Include ", etc." after multiple examples.
220     - For cases where you're providing an complete list of possible values
224 - Variable assignments:
243 - General variable naming conventions:
245   - Variable names should be lower case with few exceptions (listed here):
246     - Environment variables should be all upper case.
247     - Variables intended to be set by Robot -v parameters may be all upper case.
248   - Words within a variable name should be separated by underscores:
264   - Use good judgement in choosing variable names that are neither way too short
281   - Avoid having the variable's type as a suffix portion of the name:
302   - Consistency of variable names:
321 - Special variable naming conventions.
326   - hosts
340   - host names
354   - Short host names
367   - IP addresses
380   - Files and directories:
382     - Files:
384       - If your variable is to contain only the file's name, use a suffix of
393       - If your variable is to contain the path to a file, use a suffix of
408         To re-iterate, it doesn't matter whether the contents of the variable
413       - If the variable **must** contain an absolute path (which should be the
416     - Directories:
418       - Directory variables should follow the same conventions as file
421       - If your variable is to contain only the directory's name, use a suffix
430       - If your variable is to contain the path to a directory, use a suffix of
444         To re-iterate, it doesn't matter whether the contents of the variable
449       - If the variable **must** contain an absolute path (which should be the
451       - IMPORTANT: As a programming convention, do pre- processing on all
460   - Setup/Teardown keywords
464     - Suite Setup Execution
465     - Suite Teardown Execution
466     - Test Setup Execution
467     - Test Teardown Execution
469 - Traditional comments (i.e. using the hashtag style comments)
471   - Please leave one space following the hashtag.
479   - Please use proper English punctuation:
481     - Capitalize the first word in the sentence or phrase.
482     - End sentences (or stand-alone phrases) with a period.
484   - Do not keep commented-out code in your program. Instead, remove it entirely.
486 - Robot Template Test Cases
488   - Follow this format for Robot template test cases:
528 - The minimum required Python version is 2.7.x. In the very near future, we will
530 - Run pycodestyle on all Python files and correct errors to follow the
531   guidelines in https://www.python.org/dev/peps/pep-0008/. Note that when python
543 - Include doc strings in every function and follow the guidelines in
544   https://www.python.org/dev/peps/pep-0257/.
564 - As shown in the prior example, if your function has any arguments, include a
568 - Function definitions:
570   - Put each function parameter on its own line:
578 - Do not keep commented-out code in your program. Instead, remove it entirely.
579 - When you define a python function, observe the following conventions:
581   - Separate words with single underscores.
582   - Use lower-case letters.
603 - Documentation strings:
605   - Each documentation string should be phrased as an **English command**.
629   - Doc strings should begin with a summary line which is one terse, descriptive
658 - General variable naming conventions:
660   - Variable names should be lower case with few exceptions (listed here):
661     - Environment variables should be all upper case.
662   - Words within a variable name should be separated by underscores:
678 - Special variable naming conventions.
683   - hosts
697   - host names
711   - Short host names
724   - IP addresses
737 - Files and directories:
739   - Files:
741     - If your variable is to contain only the file's name, use a suffix of
750     - If your variable is to contain the path to a file, use a suffix of
765       To re-iterate, it doesn't matter whether the contents of the variable are
770     - If the variable **must** contain an absolute path (which should be the
773   - Directories:
775     - Directory variables should follow the same conventions as file variables.
777     - If your variable is to contain only the directory's name, use a suffix of
786     - If your variable is to contain the path to a directory, use a suffix of
800       To re-iterate, it doesn't matter whether the contents of the variable are
805     - If the variable **must** contain an absolute path (which should be the
807     - IMPORTANT: As a programming convention, do pre- processing on all dir_path
816 - Traditional comments (i.e. using the hashtag style comments)
818   - Please leave one space following the hashtag.
826   - Please use proper English punction:
828     - Capitalize the first word in the sentence or phrase.
829     - End sentences (or stand-alone phrases) with a period.
831   - Do not keep commented-out code in your program. Instead, remove it entirely.
835 We have several templates in the templates/ sub-directory. If there is a
839 - Example:
851 - Features:
853   - Help text and arg parsing started for you.
854   - Support for "stock" parameters like "quiet", "debug", "test_mode".
855   - "exit_function" pre-defined.
856   - "validate_parms" function pre-defined.
857   - "main" function follows conventional startup sequence: