openbmc/openbmc-test-automation/CONTRIBUTING.md

1 # Contributing to OpenBMC Test Automation
3 Guide to working on OpenBMC test automation. This document will always be a
4 work-in-progress, feel free to propose changes.
8 - Reference
9 …[OpenBMC CLA](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes-via-g…
10 - Reference
11 …[OpenBMC docs](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes-via-…
15 - Reference
16 …Formatting Commit Messages](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting…
20 - [Redfish Coding Guidelines](docs/redfish_coding_guidelines.md)
24 - For this project, we will write Robot keyword definitions in either Robot or
29 …- [Quit Writing Ugly Robot Code](https://esalagea.wordpress.com/2014/11/24/robot-framework-quit-wr…
30   - [Robot Dos and Don'ts](https://www.slideshare.net/pekkaklarck/robot-framework-dos-and-donts)
32 - Observe a maximum line length of 110 characters.
33 - Avoid trailing space at the end of any line of Robot code.
34 - Avoid the use of tabs.
35 - Robot supports delimiting cells with either two or more spaces or with a pipe
40   Exceptions to two-space delimiter rule:
41   - When you wish to line up resource, library or variable values:
48   - When you wish to line up fields for test templates:
55   - When you wish to indent if/else or loop bodies for visual effect:
64 - Use single spaces to make conditions more readable:
78 - When you define or call a Robot keyword, Robot pays no attention to spaces,
81   - Separate words with single spaces.
82   - Capitalize the first character of each word.
83   - Capitalize all characters in any word that is an acronym (e.g. JSON, BMC,
113 - Documentation strings:
114   - Each documentation string should be phrased as an **English command**.
134   - Doc strings should be just one terse, descriptive sentence. Remember that
162 - Tags:
163   - Create a tag for every test suite with a tag name that represents the suite
167     Create a suite Tag name from the test file name
171         Test Tags    Boot_Progress_Code
174   - Create a tag for every test case with a tag name that mirrors the test case
183 - Description of argument(s):
184   - As shown in the following example, if your keyword has any arguments,
207     - Put parentheses around your examples. Leave one space prior to the left
209     - Use "e.g." (which effectively means "for example") to set introduce your
211     - Quote string examples.
212     - Include ", etc." after multiple examples.
213     - For cases where you're providing an complete list of possible values
217 - Variable assignments:
236 - General variable naming conventions:
237   - Variable names should be lower case with few exceptions (listed here):
238     - Environment variables should be all upper case.
239     - Variables intended to be set by Robot -v parameters may be all upper case.
240   - Words within a variable name should be separated by underscores:
256   - Use good judgement in choosing variable names that are neither way too short
273   - Avoid having the variable's type as a suffix portion of the name:
294   - Consistency of variable names:
313 - Special variable naming conventions.
317   - hosts
331   - host names
345   - Short host names
358   - IP addresses
371   - Files and directories:
372     - Files:
373       - If your variable is to contain only the file's name, use a suffix of
382       - If your variable is to contain the path to a file, use a suffix of
397         To re-iterate, it doesn't matter whether the contents of the variable
402       - If the variable **must** contain an absolute path (which should be the
405     - Directories:
406       - Directory variables should follow the same conventions as file
409       - If your variable is to contain only the directory's name, use a suffix
418       - If your variable is to contain the path to a directory, use a suffix of
432         To re-iterate, it doesn't matter whether the contents of the variable
437       - If the variable **must** contain an absolute path (which should be the
439       - IMPORTANT: As a programming convention, do pre- processing on all
448   - Setup/Teardown keywords
451     - Suite Setup Execution
452     - Suite Teardown Execution
453     - Test Setup Execution
454     - Test Teardown Execution
456 - Traditional comments (i.e. using the hashtag style comments)
457   - Please leave one space following the hashtag.
465   - Please use proper English punctuation:
466     - Capitalize the first word in the sentence or phrase.
467     - End sentences (or stand-alone phrases) with a period.
469   - Do not keep commented-out code in your program. Instead, remove it entirely.
471 - Robot Template Test Cases
472   - Follow this format for Robot template test cases:
478     Test Case Name
488         [Documentation]  REST "Get" response status test.
500     Note: Normally, a template test case would have many rows of data arguments
502     template test cases that each have only one row of data which may seem to
504     for these reasons: 1) Template tests are counted as a single test. The user
512 - The minimum required Python version is 2.7.x. In the very near future, we will
514 - Run pycodestyle on all Python files and correct errors to follow the
515   guidelines in https://www.python.org/dev/peps/pep-0008/. Note that when python
527 - Include doc strings in every function and follow the guidelines in
528   https://www.python.org/dev/peps/pep-0257/.
548 - As shown in the prior example, if your function has any arguments, include a
552 - Function definitions:
553   - Put each function parameter on its own line:
561 - Do not keep commented-out code in your program. Instead, remove it entirely.
562 - When you define a python function, observe the following conventions:
563   - Separate words with single underscores.
564   - Use lower-case letters.
585 - Documentation strings:
586   - Each documentation string should be phrased as an **English command**.
610   - Doc strings should begin with a summary line which is one terse, descriptive
639 - General variable naming conventions:
640   - Variable names should be lower case with few exceptions (listed here):
641     - Environment variables should be all upper case.
642   - Words within a variable name should be separated by underscores:
658 - Special variable naming conventions.
662   - hosts
676   - host names
690   - Short host names
703   - IP addresses
716 - Files and directories:
717   - Files:
718     - If your variable is to contain only the file's name, use a suffix of
727     - If your variable is to contain the path to a file, use a suffix of
742       To re-iterate, it doesn't matter whether the contents of the variable are
747     - If the variable **must** contain an absolute path (which should be the
750   - Directories:
751     - Directory variables should follow the same conventions as file variables.
753     - If your variable is to contain only the directory's name, use a suffix of
762     - If your variable is to contain the path to a directory, use a suffix of
776       To re-iterate, it doesn't matter whether the contents of the variable are
781     - If the variable **must** contain an absolute path (which should be the
783     - IMPORTANT: As a programming convention, do pre- processing on all dir_path
792 - Traditional comments (i.e. using the hashtag style comments)
793   - Please leave one space following the hashtag.
801   - Please use proper English punction:
802     - Capitalize the first word in the sentence or phrase.
803     - End sentences (or stand-alone phrases) with a period.
805   - Do not keep commented-out code in your program. Instead, remove it entirely.
809 We have several templates in the templates/ sub-directory. If there is a
813 - Example:
825 - Features:
826   - Help text and arg parsing started for you.
827   - Support for "stock" parameters like "quiet", "debug", "test_mode".
828   - "exit_function" pre-defined.
829   - "validate_parms" function pre-defined.
830   - "main" function follows conventional startup sequence: