Reporting Issues
"Have no fear of perfection; you'll never reach it." - Marie Curie
Nothing is ever perfect; not even Program O, so it's inevitable that problems or errors will be discovered. When this happens, we are here to help you to resolve them, but in order for us to help you, we need you to help us. When trouble arises, We invite and encourage both botmasters and users alike to submit an issue, but when you do, we would appreciate it if you would follow the steps outlined below:
-
Go to https://github.com/Program-O/Program-O/issues and look through the list of currently open issues to see if any of them match your current situation to see if this might help.
-
If you find nothing there, you are encouraged to also look through any closed issues to see if the problem you're having has already been reported and solved.
-
If this hasn't helped yet, then please feel free to submit a new issue using the big, green "New Issue" button on the page linked above. When you do, however, it's strongly recommended that you provide the following information:
-
A brief, informative description of the exact problem that you're having
-
A more detailed description in the body of the post itself, telling us when the problem occurs (e.g. during installation, when using the chatbot, accessing the admin page, etc.).
-
A list of the following information about your Program O install:
-
Is Program O installed locally (your computer), or remotely (on a server on the intranet/internet), and is it accessible on the web? if it is accessible on the web, please provide a URL to it, so that we can test it directly.
-
Server OS and version (e.g. Debian 6 or Windows 8.1) and server software version (e.g. Apache 2.4, IIS 7, etc.)
-
PHP and MySQL versions
-
Client computer OS and version (leave out if Program O is installed locally)
-
Web browser brand and version (e.g. Firefox 46, Microsoft Edge browser, IE 8)
-
-
If there are any error logs (in the logs folder) or debug files (located in chatbot/debug - more on this later) that are relevant to the problem, please provide these. GitHub allows
Drag & Dropof files into your post, so it's pretty easy to include these files.
The debug files mentioned above include a ton of information about the most recent conversation volley (user input and chatbot response) for each user, but is only generated when a user accesses the bot. If you're having trouble with the install process, or when using the admin page, then a debug file is useless, so there is no need to include them in these situations. However, if you're getting unexpected responses from the chatbot (or no response at all), the debug file is the best place to look. At some point I'll post a "Debugging 101" article for those adventurous souls who would like to be able to troubleshoot chatbot issues on their own, or even for those who would like to see what goes on "behind the scenes", but for now, let's just concentrate on including the correct file in your issue.
Ok, as mentioned before, a debug file contains a lot of information about a specific conversation volley, but only if Program O is configured to generate them (they can take up a lot of space, and slightly affect performance, so they can be set to one of several "modes" (Write the info to a file, display the debug info within the page itself {only works with the HTML interface}, include the debug information in the page's source {also HTML only}, or email the information {Strongly discouraged, as this will generate a new email for every time a user sends input to the chatbot}), and debugging "levels" (no debugging at all, errors only, errors and general info, errors and info and SQL queries, or "show everything"). When generating debugging information to add to a GitHub issue, it's best to configure Program O to save the debug data to a file, and set the level to "show everything". This can be done in the admin page, under the "Current Bot: ([bot name]) panel. simply use the dropdown options in the lower-right corner of the panel to set both mode and level, and hit the Update button, and you're set.
Once the debug options are set and you've gotten the "unexpected" response from the chatbot, there are some things to remember. First, the debug file only captures one volley at a time, so if you get the response that's giving you trouble, stop talking to the bot immediately, or the debugging information will be lost. You need to next locate the correct debug file to attach to your post. If you're the only "user" that the chatbot has interacted with this could be a fairly simple process, as there may be only one debug file, but this isn't always the case, so here's how to figure out which debug file is the one you need.
No matter which interface you're using for your chatbot (HTML, JSON or XML), the form used to send user inputs and view chatbot responses will always have a hidden form field called convo_id. This field will contain the conversation ID that Program O uses to keep track of the user, and this ID is used for the file name of the debug file. For example, in the HTML interface, that hidden form field might look like this:
<input type="hidden" name="convo_id" id="convo_id" value="vvrpccnhaust90qt04hjgeogq2" />
The XML and JSON interfaces will look similar. In this example, the conversation ID is "vvrpccnhaust90qt04hjgeogq2" (without the quotes, of course), so the debug file will be named vvrpccnhaust90qt04hjgeogq2.txt, and will be found in the chatbot/debug folder. Just locate that file in the debug folder, download it to your computer if it's on a web server, then drag it to your GitHub issue post and you're done.
By following these steps, you help us to find the cause of the issue much more quickly than if you don't, and this helps us all. So please, whenever possible, use this information to let us know when you have a problem, and we'll get your issue resolved in record time.
