ENH: Automated Bug Reporting

MANIFEST.in

@@ -1,5 +1,6 @@
 include versioneer.py
 include hutch_python/_version.py
+include hutch_python/templates/*
 include hutch_python/logging.yml
 include hutch_python/cookiecutter/*
 include hutch_python/cookiecutter/*/*

bin/post-issues

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+import os
+import getpass
+import logging
+import argparse
+
+from hutch_python.constants import BUG_REPORT_PATH
+from hutch_python.bug import post_to_github
+
+logger = logging.getLogger(__name__)
+
+
+description = """\
+Post all of the stored issue to https://github.com/pcdshub/Bug-Reports
+
+This requires a valid GitHub account that is authorized to post issues in
+the pcdshub organization. By default this script will be run automatically at a
+frequent interval, but if that is failing or you feel the need to immediately
+push an issue upstream this script can be utilized.
+
+
+"""
+
+
+def main():
+    """Post all issues in BUG_REPORT_PATH"""
+    # Create argument parser
+    fclass = argparse.RawDescriptionHelpFormatter
+    parser = argparse.ArgumentParser(epilog=description,
+                                     formatter_class=fclass)
+    parser.add_argument('-u', '--user', dest='username',
+                        default=None,
+                        help="Username for GitHub account")
+    parser.add_argument('-p', '--pw', dest='password',
+                        default=None,
+                        help='Password for GitHub account. This will be '
+                             'queried for if not entered at call time.')
+    args = parser.parse_args()
+    # Ask for the password once so if it isn't asked to repetitively
+    pw = args.password or getpass.getpass()
+    # Run post_to_github on every stored issue
+    for issue in os.listdir(BUG_REPORT_PATH):
+        if issue.endswith('.json'):
+            try:
+                logger.info('Posting %s ...', issue)
+                post_to_github(os.path.join(BUG_REPORT_PATH, issue),
+                               user=args.username, pw=pw)
+            except Exception:
+                logger.exception("Error posting %s", issue)
+
+
+if __name__ == '__main__':
+    # Configure logger
+    logging.basicConfig(level=logging.INFO)
+    # Post issues
+    main()

conda-recipe/meta.yaml

@@ -28,6 +28,9 @@ requirements:
     - lightpath >=0.3.0
     - cookiecutter >=1.6.0
     - matplotlib
+    - simplejson
+    - requests
+    - jinja2
 
 test:
   imports:

docs/source/bug.rst

@@ -0,0 +1,14 @@
+bug.py
+======
+Functionality associatted with bug reports
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   hutch_python.bug.get_current_environment
+   hutch_python.bug.get_last_n_commands
+   hutch_python.bug.get_text_from_editor
+   hutch_python.bug.report_bug
+   hutch_python.bug.post_to_github
+

docs/source/index.rst

@@ -40,6 +40,7 @@
    :caption: Internal API Reference
    :hidden:
 
+   bug
    cache
    cli
    ipython_log

docs/source/log_setup.rst

@@ -8,6 +8,7 @@ log_setup.py
    :nosignatures:
 
    setup_logging
+   get_session_logfiles
    get_console_handler
    get_console_level
    set_console_level

docs/source/user_utils.rst

@@ -1,9 +1,26 @@
 Useful Utilities
 ================
 
-The ``hutch_python.utils`` and ``hutch_python.namespace`` modules have
-functions that may be broadly useful.
-
+Reporting Issues
+----------------
+.. automodule:: hutch_python.bug
+
+   .. autofunction:: report_bug
+
+Issue Lifecyle
+^^^^^^^^^^^^^^
+We can not expect that every operator on the beamline has a valid Github
+account. To get around this, when you call `report_bug` we dump a JSON
+description of the issue into a standard NFS directory. Then by a regular CRON
+job we will post this issue to https://github.com/pcdshub/Bug-Reports. This
+leads to a slight delay but also allows to have issues posted by persons
+without valid GitHub accounts. Once issues are received on GitHub the
+appropriate action will be made by the PCDS staff. This may mean a deeper look
+at the linked log files and/or creating a distilled issue or action item in a
+different repository. 
+
+Safe Loading
+------------
 `hutch_python.utils.safe_load` can be used as a shortcut for wrapping code
 that may or may not succeed to prevent a bad submodule from interrupting the
 ``hutch-python`` load sequence. This means that if the ``Attenuator`` class is
@@ -23,6 +40,8 @@ For example, this will complete successfully but show a warning:
 The reason for the failure with the full traceback will be saved to the log
 file and will be visible in the terminal if you are in `debug mode <debug>`.
 
+User Namespaces
+---------------
 `hutch_python.namespace.class_namespace` can be used to create your own object
 groupings by type. This will find all objects loaded by hutch python plus all
 objects in your global environment, and accumulate them if they match a given