Githawk: Document PAT requirements

[tripleee]

I was unable to comment on issues in a repo I contribute to and I ignored it for a while. Now, they made me a co-maintainer and I _still_ could not comment, so I decided to look further into it.

Sorry if this comes off as rambling; I'll simply try to describe my experience and then suggest some changes which might be lame or misdirected because I don't understand the underlying mechanisms properly. Maybe scroll down to "Suggestions" below.

TL;DR

When creating a Personal Access Token in the "Developer" section of your Github account, you need to grant GitHawk the following;

• repo
• user
• notifications

Transcript

This is an outline of a series of "paper cuts" I experienced whilst figuring this out.

When you can't comment on an issue in GitHawk, the red warning box about possibly requiring a Personal Access Token was not always visible, so I probably scrolled past it or swiped my screen so I could not see it a number of times.

When I finally did pay proper attention, it said I can change this in settings. But the nondescript dialog in Settings > Accounts was not understandable to me. I can click on PAT and get a text entry dialog box but what should I put there? I had to Google, and spent I think on the order of 15 minutes forming a picture of what it was actually talking about.

Googling got me https://github.com/GitHawkApp/GitHawk/issues/420 (which ultimately perhaps this should be a duplicate of?) but it does not describe which privileges are requred or how to grant them. It did give me enough to understand how to articulate a better Google search, which took me to https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line

That's probably the most useful official link there is at the moment, though it confusingly talks about "the command line" rather than an app; and the instructions are for the Desktop version of Github. Switching to "Desktop" when visiting on mobile still didn't expose the menu where I could actually create a PAT. These are obviously problems with Github's documentation and UI and nothing GitHawk can directly affect; but it affects how you might want to tackle documenting this facility.

Now I was finally able to create a PAT, but which privileges does GitHawk need? I tried to google for a bit, but I just kept going in circles. So I guessed, and thought I made some pretty decent guesses. So what if I give it a couple of bits too much.

Access to inbox not permitted.

Finally I discovered that
https://github.com/GitHawkApp/GitHawk/blob/master/SECURITY.md describes the privileges GitHawk wants, but it doesn't mention PAT at all. I know enough about these things to connect "OAuth" and "PAT" but I suspect many users don't; and even if you do, putting this explicitly in the manual or a help page would have saved me some effort. I had actually looked at this page before, but since it didn't mention PAT at all, I didn't read it properly at the time.

Suggestions

Chronologically collecting suggested changes, with an ad-hoc priority from 0 to 5;

• (Pri: 2) The red warning box in the app should be harder to miss. Could it perhaps be displayed across the top of the screen where it's less likely to be lost in other screen updates and distractions such as the on-screen keyboard?
• (Pri: 4) Make the PAT screen in Settings less opaque. Could it have a short description and/or perhaps a link to more information on-line?
• (Pri: 1) Integrate PAT creation into GitHawk? This would make it very easy for new users, but is probably too complex.
• (Pri: 5) Explicitly document which precise privileges you have to grant GitHawk when creating a Personal Access Token.

[j-f1]

I think the last three issues could be helped by adding a button that opens this link: https://github.com/settings/tokens/new?scopes=user,repo,notifications&description=GitHawk+Token

This will take you to a page that has all the necessary permissions pre-checked and the description box pre-filled. All the user would have to do would be to copy the token and paste it back into the app.

[tripleee]

(Oh I'm slowly coming to realize that #420 is really about something else entirely, and the PAT discussion there is completely tangential.)

[bridger]

I ran into trouble trying to add a PAT too. I didn't guess the right permissions, so adding the PAT caused the app to get errors every time it tried to fetch data. A related bug was that setting a PAT to an empty string didn't work, so I was unable to use Githawk until I found this issue with instructions for making a functional PAT.