Update README.md and CONTRIBUTING.md documentation
Changes:
- Replace deprecated code with latest example for usage.
- Alignment and spacing changes.
- Move template example from README.md to CONTRIBUTING.md.
Change-Id: I0b42667748f4657d3816f3aa6ec01b7be58e3332
Signed-off-by: George Keishing <gkeishin@in.ibm.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3134732..2a28196 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,8 +12,8 @@
- For this project, we will write Robot keyword definitions in either Robot
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.
+- 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
@@ -43,320 +43,634 @@
... Run Keywords Key1 parms
... AND Key2 parms
```
-- Use spaces to make conditions more readable:
-
- Correct example:
- ```
- Run Keyword If '${var1}' == '${0}' My Keyword
- ```
- Incorrect example:
- ```
- Run Keyword If '${var1}'=='${0}' My Keyword
- ```
-- 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
- ```
-- Description of argument(s):
- - As shown in the following example, if your keyword 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 keyword. Include
- real data examples wherever possible and applicable. Leave at least 2 spaces
- between the argument name and the description. Align all description text as
- shown in the example below.
-
- Example:
- ```
- Get URL List
- [Documentation] Return list of URLs under given URL.
- [Arguments] ${openbmc_url}
-
- # Description of argument(s):
- # openbmc_url URL for list operation (e.g.
- # "/xyz/openbmc_project/inventory").
- # policy Power restore policy (e.g "RESTORE_LAST_STATE",
- # ${RESTORE_LAST_STATE}).
- ```
-- 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
- ```
- - Setup/Teardown keywords
-
- Use standardized names for setup and teardown keywords:
- - Suite Setup Execution
- - Suite Teardown Execution
- - Test Setup Execution
- - Test Teardown Execution
-- 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.
-
+- Use spaces to make conditions more readable:
+
+ Correct example:
+ ```
+ Run Keyword If '${var1}' == '${0}' My Keyword
+ ```
+ Incorrect example:
+ ```
+ Run Keyword If '${var1}'=='${0}' My Keyword
+ ```
+- 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
+ ```
+- Description of argument(s):
+ - As shown in the following example, if your keyword 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 keyword. Include
+ real data examples wherever possible and applicable. Leave at least 2 spaces
+ between the argument name and the description. Align all description text as
+ shown in the example below.
+
+ Example:
+ ```
+ Get URL List
+ [Documentation] Return list of URLs under given URL.
+ [Arguments] ${openbmc_url}
+
+ # Description of argument(s):
+ # openbmc_url URL for list operation (e.g.
+ # "/xyz/openbmc_project/inventory").
+ # policy Power restore policy (e.g "RESTORE_LAST_STATE",
+ # ${RESTORE_LAST_STATE}).
+ ```
+- 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
+ ```
+ - Setup/Teardown keywords
+
+ Use standardized names for setup and teardown keywords:
+ - Suite Setup Execution
+ - Suite Teardown Execution
+ - Test Setup Execution
+ - Test Teardown Execution
+- 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
-----------------------
-- The minimum required Python version is 2.7.x.
-- 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.
+- The minimum required Python version is 2.7.x.
+- 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.
+- 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.
+
+Template Usage Guidelines
+-------------------------
+We have several templates in the templates/ sub-directory. If there is a
+template that applies to your programming situation (Python, bash, etc.),
+it should be used to create new programs as in the following example
+
+- Example:
+
+ ```
+ $ cd templates
+ $ cp python_pgm_template ../bin/my_new_program
+ ```
+
+These templates have much of your preliminary work done for you and will help
+us all follow a similar structure.
+
+- Features:
+ - Help text and arg parsing started for you.
+ - Support for "stock" parameters like "quiet", "debug", "test_mode".
+ - "exit_function" and "signal_handler" defined.
+ - "validate_parms" function pre-created.
+ - "main" function follows conventional startup sequence:
+
+ ```
+ if not gen_get_options(parser, stock_list):
+ return False
+
+ if not validate_parms():
+ return False
+
+ qprint_pgm_header()
+
+ # Your code here.
+ ```
diff --git a/README.md b/README.md
index 68e2839..98a9bcd 100755
--- a/README.md
+++ b/README.md
@@ -92,167 +92,140 @@
```
**Tox Command Line**
-Install the python dependencies for tox
-```shell
+* Install the python dependencies for tox:
+ ```
$ easy_install tox
$ easy_install pip
-```
+ ```
-Initialize the following environment variable which will be used during testing
-```shell
+* Initialize the following environment variables which will be used during testing:
+ ```
$ export OPENBMC_HOST=<openbmc machine ip address>
$ export OPENBMC_PASSWORD=<openbmc password>
$ export OPENBMC_USERNAME=<openbmc username>
$ export OPENBMC_MODEL=[./data/Barreleye.py, ./data/Palmetto.py, etc]
$ export IPMI_COMMAND=<Dbus/External>
$ export IPMI_PASSWORD=<External IPMI password>
-```
-
-```shell
-
- Use following parameters for PDU:
+ ```
+* For tests requiring PDU, set the following environment variables as well:
+ ```
$ export PDU_IP=<PDU IP address>
$ export PDU_USERNAME=<PDU username>
$ export PDU_PASSWORD=<PDU password>
$ export PDU_TYPE=<PDU type>
$ export PDU_SLOT_NO=<SLOT number>
+ ```
+ Note: For PDU_TYPE we support only synaccess at the moment.
- for PDU_TYPE we support only synaccess at the moment
-
-Use the following variables for Qemu test run
-==========================================================
+* For QEMU tests, set the following environment variables as well:
+ ```
$ export SSH_PORT=<ssh port number>
$ export HTTPS_PORT=<https port number>
-
-Use the following variables for BIOS update testing
-==========================================================
+ ```
+* For BIOS tests, set the following environment variables as well:
+ ```
$ export PNOR_IMAGE_PATH=<path to>/<machine>.pnor
+ ```
-```
-
-Run tests
-```shell
+* Run tests:
+ ```
$ tox -e tests
-```
+ ```
-How to test individual test
-```shell
- One specific test
- $ tox -e default -- -t '"DIMM0 no fault"' tests/test_sensors.robot
+* How to run individual test:
- No preset environment variables, default configuration for all supported systems.
+ One specific test:
+ ```
+ $ tox -e default -- --include Power_On_Test tests/test_basic_poweron.robot
+ ```
+ No preset environment variables, default configuration for all supported
+ systems:
+ ```
$ OPENBMC_HOST=x.x.x.x tox -e default -- tests
-
- No preset environment variables, one test case from one test suite
- $ OPENBMC_HOST=x.x.x.x tox -e barreleye -- -t '"DIMM0 no fault"' tests/test_sensors.robot
-
- No preset environment variables, one test suite for a palmetto system
- $ OPENBMC_HOST=x.x.x.x tox -e palmetto -- tests/test_sensors.robot
-
- No preset environment variables, the entire test suite for a barreleye system
- $ OPENBMC_HOST=x.x.x.x tox -e barreleye -- tests
-
+ ```
+ No preset environment variables, one test case from a test suite:
+ ```
+ $ OPENBMC_HOST=x.x.x.x tox -e default -- --include Power_On_Test tests/test_basic_poweron.robot
+ ```
+ No preset environment variables, the entire test suite:
+ ```
+ $ OPENBMC_HOST=x.x.x.x tox -e default -- tests
+ ```
Default CI test bucket list:
+
No preset environment variables, the entire test suite excluding test
- cases using argument file.
- $ OPENBMC_HOST=x.x.x.x tox -e barreleye -- --argumentfile test_lists/skip_test tests
+ cases using argument file:
+ ```
+ $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/skip_test tests
+ ```
Exclude test list for supported systems:
+ ```
Barrleye: test_lists/skip_test_barreleye
Palmetto: test_lists/skip_test_palmetto
Witherspoon: test_lists/skip_test_witherspoon
-```
+ ```
-It can also be run by passing variables from the cli...
-```shell
- Run one test suite using using pybot
- $ pybot -v OPENBMC_HOST:<ip> -v OPENBMC_USERNAME:root -v OPENBMC_PASSWORD:0penBmc -v OPENBMC_MODEL:<model path> tests/test_time.robot
-
- Run entire test suite using using pybot
- $ pybot -v OPENBMC_HOST:<ip> -v OPENBMC_USERNAME:root -v OPENBMC_PASSWORD:0penBmc -v OPENBMC_MODEL:<model path> tests
-
- Run entire test suite using external ipmitool
- $ pybot -v OPENBMC_HOST:<ip> -v OPENBMC_USERNAME:root -v OPENBMC_PASSWORD:0penBmc -v IPMI_COMMAND:External -v IPMI_PASSWORD:PASSW0RD -v OPENBMC_MODEL:<model path> tests
-```
-
-Run extended tests
-```shell
- Set the preset environment variables, run test suite for a barreleye system
- $ OPENBMC_HOST=x.x.x.x tox -e barreleye -- extended/test_power_restore.robot
-
- Similarly for Network, PDU and update BIOS
+* Run extended tests:
For BMC code update, download the system type *.all.tar image from https://openpower.xyz
and run as follows:
- For Barreleye system
- python -m robot -v OPENBMC_HOST:x.x.x.x -v FILE_PATH:downloaded_path/barreleye-xxxx.all.tar extended/code_update/update_bmc.robot
-
- For loop test (Default iteration is 10)
- python -m robot -v OPENBMC_HOST:x.x.x.x -v OPENBMC_SYSTEMMODEL:xxxxxx -v ITERATION:n -v LOOP_TEST_COMMAND:xxxxxx extended/full_suite_regression.robot
- Below is sample command using tox to test only fw version using Barreleye system for 5 times
+ For Barreleye system:
+ ```
+ $ robot -v OPENBMC_HOST:x.x.x.x -v FILE_PATH:downloaded_path/barreleye-xxxx.all.tar extended/code_update/update_bmc.robot
+ ```
+ For loop test (default iteration is 10):
+ ```
+ $ robot -v OPENBMC_HOST:x.x.x.x -v OPENBMC_SYSTEMMODEL:xxxxxx -v ITERATION:n -v LOOP_TEST_COMMAND:xxxxxx extended/full_suite_regression.robot
+ ```
+ Example using tox testing a test suite for 5 times:
+ ```
OPENBMC_HOST=x.x.x.x LOOP_TEST_COMMAND="--argumentfile test_lists/skip_test tests/test_fw_version.robot" ITERATION=5 OPENBMC_SYSTEMMODEL=barreleye tox -e barreleye -- ./extended/full_suite_regression.robot
-```
+ ```
-Jenkins jobs tox commands
-```shell
- HW CI tox command
- Set the preset environment variables, run HW CI test for a barreleye system
- $ OPENBMC_HOST=x.x.x.x tox -e barreleye -- --argumentfile test_lists/HW_CI tests
+**Jenkins jobs tox commands**
+* HW CI tox command:
+ ```
+ $ OPENBMC_HOST=x.x.x.x tox -e default -- --argumentfile test_lists/HW_CI tests
+ ```
-```
+**Tools**
-Template to be used to create new stand-alone python programs.
-```shell
+* Github script:
-If you wish to create a new python stand-alone program, please copy bin/python_pgm_template to your new name and then begin your work. Example:
+ Command to get GitHub issues (any GitHub repository) report in CSV format:
-cd bin
-cp python_pgm_template my_new_program
+ Note: On Prompt "Enter your GitHub Password:" enter your GitHub password.
-This template has much of your preliminary work done for you and it will help us all follow a similar structure.
+ Usage:
+ ```
+ $ cd tools/
+ $ python github_issues_to_csv <github user> <github repo>
+ ```
+ Example for getting openbmc issues:
+ ```
+ $ python github_issues_to_csv <github user> openbmc/openbmc
+ ```
+ Example for getting openbmc-test-automation issues:
+ ```
+ $ python github_issues_to_csv <github user> openbmc/openbmc-test-automation
+ ```
-Features:
-- Help text and argparsing started for you.
-- Support for "stock" parameters like quiet, debug, test_mode.
-- exit_function and signal_handler defined.
-- validate_parms function pre-created.
-- main function follows conventional startup:
+* Generate Robot test cases documentation:
- if not gen_get_options(parser, stock_list):
- return False
+ Usage:
+ ```
+ $ ./generate_test_document <Robot test directory path> <test case document file path>
+ ```
- if not validate_parms():
- return False
+ Example for generating tests cases documentation for tests directory:
+ ```
+ $ ./generate_test_document tests testsdirectoryTCdocs.html
+ ```
- qprint_pgm_header()
-
- # Your code here.
-
-```
-
-Command to get GitHub issues (any GitHub repository) report in CSV format
-Note: On Prompt "Enter your GitHub Password:" enter your GitHub password.
-```shell
-python ./tools/github_issues_to_csv <github user> <github repo>
-
-Example for getting openbmc issues
-python ./tools/github_issues_to_csv <github user> openbmc/openbmc
-
-Example for getting openbmc-test-automation issues
-python ./tools/github_issues_to_csv <github user> openbmc/openbmc-test-automation
-```
-
-
-Command to generate Robot test cases test documentations
-
-```shell
-./tools/generate_test_document <Robot test cases directory path> <test case document file path>
-
-Example for generating tests cases documentation for tests directory
-./tools/generate_test_document tests testsdirectoryTCdocs.html
-
-Example for generating tests cases documentation (tests,gui,extended TCs)
-# Note: Invoke the tool with out argument
-./tools/generate_test_document
-```
+ Example for generating tests cases documentation (tests, gui, extended TCs):
+ Note: Invoke the tool without argument:
+ ```
+ $ ./generate_test_document
+ ```