☰

HelpMe

A command line tool for helping you out

Github Helper

Github is the default client. To use Github, you can optionally create a personal access token for submission using the API, or skip to have HelpMe generate and open a URL for you.

Generating an Access Token

You can call it whatever you like (helpme-client in the example below) and check the box for the scope “repo.” You should export the token to your environment.

export HELPME_GITHUB_TOKEN=xxxxxxxxxxxxxx

If provided, the token will be found the first time you run the client, and cached in your $HOME/helpme.cfg file. If you are interested in how this works, see the developer documentation.

Ask for Help

The main command will be to ask for help from Github. This means we will do the following:

  • Ask you for the repository unique resource identifier, in the format owner/repo
  • Ask you to describe the issue that you are having
  • (optional) record an asciinema to show us what is going on
  • (optional) you can choose to include a whitelisted set of environment variables

Let’s show the most common use case, we can either ask for help for general Github, and then be prompted for the repository. You will be asked to enter a Github repository if you don’t provide one on the command line, and then if you want to record an asciinema.

$ helpme github
[helpme|github]
Hello Friend! I'll help you post a Github issue today.
What is the Github repository to post to? (e.g., username/reponame):

or you can give the name of the repository off the bat, and skip this prompt. In the example below, I’m asking to post an issue to this repo, vsoch/helpme.

$ helpme github vsoch/helpme
[helpme|github]
Hello Friend! I'll help you post a Github issue today.
Please describe the issue you are having: I want to post a test issue for HelpMe Github!
Would you like to send a terminal recording?
Please enter your choice [Y/N/y/n] : Y
asciinema: recording asciicast to /tmp/helpme.5hcz3w6v.json
asciinema: press <ctrl-d> or type "exit" when you're done
Now using node v8.10.0 (npm v5.6.0)
vanessa@vanessa-ThinkPad-T460s:~/Documents/Dropbox/Code/researchapps/helpme/helpme-cli$ echo "Look at my awesome terminal! So many issues..."
Look at my awesome terminal! So many issues...
vanessa@vanessa-ThinkPad-T460s:~/Documents/Dropbox/Code/researchapps/helpme/helpme-cli$ exit
exit
asciinema: recording finished
asciinema: asciicast saved to /tmp/helpme.5hcz3w6v.json
Asciinema  If you need to run helpme again you can give
                    the path to this file with  --asciinema /tmp/helpme.5hcz3w6v.json
Environment  USER|TERM|SHELL|PATH|LD_LIBRARY_PATH|PWD|JAVA_HOME|LANG|HOME|DISPLAY
Is this list ok to share?
Please enter your choice [Y/N/y/n] : Y
https://www.github.com/vsoch/helpme/issues
[submit=>github]

If I need to do it again, I can supply the asciinema on the command line.

$ helpme github --asciinema /tmp/helpme.5hcz3w6v.json vsoch/helpme

And here is the issue created! Awesome!

Headless

If you have a python library and want to headlessly submit an issue, you can easily do that from within Python.

A Simple Example

Here is the simplest use case - just providing a repository.

from helpme.main import get_helper
helper = get_helper(name="github")

By default, the helper will not require a GitHub token (HELPME_GITHUB_TOKEN exported to the environment) and will interactively open the browser for the user. However, if you need to ensure that the token is provided, just add the argument:

helper = get_helper(name="github", require_token=True)

The client will exit with an error message if the token is not found. Now, for the simplest use case (either with or without the token) you can just provide a repository.

helper.run_headless(repo="rseng/github-support")

The above will return the user’s system information, along with environment.

Add Additional Error Context

However, you likely want to provide a little more context about the error. The function also accepts an argument for title or body, and an identifier string that can be used to generate a hash that would uniquely identify the issue for further action once on GitHub. In the example below, we use datalad to generate a dictionary of output, and we will submit it to the repository datalad/datalad-helpme.

from datalad.api import wtf 
repo = "datalad/datalad-helpme"
body = "<details>\n\n%s</details>" % wtf()

Notice that we are putting the body in a details div - this html element will hide most of the data (which is dumped json) in the actual issue, and make it easier to parse further (if desired). Next, let’s run the helper headlessly. Note that this will currently still confirm the environment variables being sent from the user.

helper.run_headless(repo=repo, body=body, title=title)

The above will still require confirmation to send the user environment, and then will post the issue to datalad/datalad-helpme.

Eliminate Confirmation

The user is prompted to confirm the whitelisted set of environment variables:

Environment  USER|TERM|SHELL|PATH|LD_LIBRARY_PATH|PWD|JAVA_HOME|LANG|HOME|DISPLAY
Is this list ok to share?
Please enter your choice [Y/N/y/n] :

For a totally headless and automated route, just set confirm to False.

helper = get_helper(name="github", confirm=False)

Provide Identifier

A string can be provided that will (by default) be converted to an md5 hash and written at the bottom of the issue. It’s useful to derive this from some string that could uniquely be used to identify the error (such as a message or metadata from an error traceback).

try:
    import thisdoesnotexist
except Exception as exc:
    helper.run_headless(repo=repo, body=body, title=title, identifier=exc.msg)

If you want to generate your own identifier or hash (and not have helpme do it for you) set generate_md5 to False:

try:
    import thisdoesnotexist
except Exception as exc:
    helper.run_headless(repo=repo, body=body, title=title, identifier="custom-id", generate_md5=False)

Given an identifier, you can use a GitHub workflow (responding to new issues) to parse and then categorize the issue, and update some flat file database (perhaps stored in a support repository?) and post an update on the issue, for example:

This issue is a duplicate of #4, closing This issue has been assigned to @vsoch

The action that you choose to take is up to you! You can take a look at the example github-support repository for an example script and GitHub action to do this.

Related pages