Reporting Issues

One advantage of standardizing the logging system and startup scripts with hutch-python is programmatically being able to gather information about the current Python environment. One common use case for much of this information is being able to diagnose software bugs after the fact if we are diligent about recording the pertinent information. The hutch_python.bug.report_bug command wraps much of this functionality up by asking a few simple questions of the operator and noting the current environment and log file. By the end of the function we should have:

  • A one line description of the problem

  • A more verbose explanation of the issue and how it affects operations

  • A name to follow up with additional questions / closeout

  • The commands entered by the operator

  • The current CONDA environment

  • Relevant logfiles written to by this Python session

  • Capture output printed to the terminal

  • Any packages installed in “development” mode

This command is available as both an actual Python function and an IPython magic. The ladder allows you to pinpoint the exact function that is causing issues.

%report_bug my_buggy_function()

If you call report_bug as a regular function you can specify a number of past commands you want to include in the overall report. This allows you to posthumously report issues without running the actual function again.

hutch_python.bug.report_bug(title=None, description=None, author=None, prior_commands=None, captured_output=None, **kwargs)

Report a bug from the IPython session

The purpose of this command is to collect the necessary information to later help diagnose and troubleshoot the issue. This is written as an interactive tool, but it can be used in a non-interactive way by entering the information on the call.

By the end we should have gathered:

  • A brief description of the problem

  • The relevant commands to the bug report

  • Name of the current CONDA environment

  • Any packages installed in “development” mode

  • Relevant logfiles

  • Name of bug report author

Parameters:

  • title (str, optional) – One sentence description of the issue

  • description (str, optional) – Written description of problem. If this is not provided, a text editor is launched that request the information from the user

  • author (str, optional) – Name of bug report author. If not provided, this is requested from the user via command line

  • prior_commands (int, optional) – Number of prior commands to capture. If this is not provided, this is requested from the user via command line.

  • captured_output (str, optional) – Captured output from the command

  • kwargs – Pass authentication information to post_to_github()

Issue Lifecyle

After reporting the issue on the command line, an issue will be created at https://github.com/pcdshub/Bug-Reports. This will alert those subscribed to this repository via email about the current issue and 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.