-
Notifications
You must be signed in to change notification settings - Fork 1
Contribution Guidelines
When possible, issues should be focused and executable tasks.
Title issues like items in a to-do list: "Do this". "Add this". "Implement this". "Test this". The title should follow typical sentence capitalization. Only the first letter of the title and other proper nouns should be capitalized. Ex. "Set up arguments parsing and logging configuration".
Issues should be tasks that can be resolved quickly. If an issue describes a task that requires coordination with many other features, the issue should be broken down into smaller issues. For instance, "Add usage documentation" is too broad of an issue because it depends on all of the implementation to be completed and use cases to be known. A better approach would be to create a documentation issue for each component that has been completed. Ex. "Add usage documentation for logging levels".
Please comment the reason before closing an issue.
To resolve an issue, create a issue branch off of master that abides by the naming convention: feature/i-<issue number>-<short>-<issue>-<title>
. Ex. feature/i-4-args-parse-logging-config
.
If you would like to branch off of an issue, simply name the branch i-<issue number>/<short>-<task>-<title>
. Ex. i-4/creating-parser
.
Use hyphens, not underscores.
Code that is done and ready to request to be merged into master via a pull request must be tested, commented, and make appropriate use of logging.
For each program file, create its corresponding test file within the /tests
directory. The test file should be named test_<file>_<name>.py
. Ex. If the test file is for the program file parse_arguments.py
, it should be named test_parse_arguments.py
.
Each function, if possible, should be covered by a test case. The test cases should be named test_<function>_<name>_<condition>_<description>
. Ex. If you are testing the parse_arguments
function in the parse_arguments.py
file, a test case may be named test_parse_arguments_debug_logging_level
. This would indicate that you are testing the parse_arguments
function with the debug logging level condition.
Each function should include a Docstring comment after the function signature. E.g.:
function my_python_fcn():
""" A description of what my_python_fcn() does """
To log, include the following in each file:
import logging
...
logging.info("General (non-technical) comment about how the program is running. Used for normal behavior.")
logging.debug("More technical comment about how the program is running. May describe inputs and outputs of specific functions. Used for normal behavior")
logging.error("Comment about what went wrong in the program. Could be used within a catch block or conditional that checks for erroneous activity. Used for abnormal/deleterious behavior.")