User Guide
Bugit is a TUI (Terminal user interface) bug reporting tool specifically designed to work with checkbox. This guide will assume the user knows how to use checkbox to run test plans. Bugit allows mouse interactions so you can use it like a regular desktop app.
Use bugit.bugit-v2 jira -h or bugit.bugit-v2 lp -h to list all options. For most use cases, directly launch sudo bugit.bugit-v2 jira or sudo bugit.bugit-v2 lp to enter the TUI.
$ bugit.bugit-v2 jira -h
Usage: bugit.bugit-v2 jira [OPTIONS]
Submit a bug to Jira
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --checkbox-submission -s FILE The .tar.xz file submitted by checkbox │
│ after a test session has finished. If │
│ this option is specified, Bugit will │
│ read from this file instead of │
│ checkbox sessions and enter the editor │
│ directly │
│ --cid -c TEXT Canonical ID (CID) of the device under │
│ test. This is used to pre-fill the │
│ "CID" field in the editor │
│ --sku -k TEXT Stock Keeping Unit (SKU) string of the │
│ device under test. This is used to │
│ pre-fill the "SKU" field in the editor │
│ --project -p TEXT Project name (case sensitive) like │
│ STELLA, SOMERVILLE. This is used to │
│ pre-fill the "Project" field in the │
│ editor │
│ --assignee -a TEXT Assignee ID. For Jira it's the │
│ assignee's email. This is used to │
│ pre-fill the "Assignee" field in the │
│ editor │
│ --platform-tags -pt TEXT Platform Tags. They will appear under │
│ "Components" on Jira. This is used to │
│ pre-fill the "Platform Tags" field in │
│ the editor │
│ --tags -t TEXT Additional tags on Jira. This is used │
│ to pre-fill the "Tags" field in the │
│ editor │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
After a checkbox session has started (doesn't have to finish), bugit will list them in the landing page.
These correspond to the sessions under /var/tmp/checkbox-ng/sessions. Click on a session to list failed and crashed jobs:
Tip
Although bugit is designed to work with checkbox, it's not coupled. You can select the "No session" or "No job" options to skip to editor.
Bugit should enter the editor page.
The editor page is basically a form with some pre-filled fields for convenience.
Warning
The 2 required fields are the title and project name. Once these 2 fields are filled in, the submit button at the bottom of the page will light up and allow the bug to be submitted
Once you are done editing the bug report, scroll to the bottom of the page and click submit. Bugit will now ask you for an authentication token.
Follow the link on that page and generate a classic API token, not the token with scopes
As with all API tokens, you should keep this token safe like a password. If you click the "Cache credentials until next boot", bugit will temporarily write your token to the snap's /tmp directory, which is cleared after a reboot. This option is NOT selected by default.
Bugit will display a authenticator wizard on screen and generate a URL. Note that the authentication URL may be clipped if your terminal is too small. Use your terminal's shortcut to zoom out and make sure to paste the URL ending with "DESKTOP_INTEGRATION" into the browser. This URL will take you to launchpad's authentication page where you can choose how long bugit's permission will last. The recommended length is 1 hour. Once you are done and launchpad tells you to return to the application, come back to bugit and click "Finish Browser Authentication".
If successful, a new, green button will appear that allows you to enter the submission page.
Now bugit will start creating the bug and uploading the attachments. There's nothing to do here, just sit back and wait for bugit to do its job.
Bugit has a auto-save feature that will capture the current state of your bug report every other second (behaves exactly like VS Code's afterDelay setting). The auto-save status is shown on the top left corner of the editor page:
After you relaunch bugit, all the auto-save files will be listed first before the session selection screen:
Click on any of the auto-save buttons to jump to the editor with the data from that save.