search

TugboatQA / docs

Tugboat Docs
https://docs.tugboat.qa
MIT License
9 stars 18 forks source link

Add API token authorization details #244

Closed dacharyc closed 4 years ago

dacharyc commented 4 years ago

Tagging you for review, Ben, because this documentation is for your "needs documentation" ticket (I'm about to archive it) and tagging you, James, because this info is mostly from your excellent gist and I'd love you to review for accuracy/details.

bchavet commented 4 years ago

I was expecting to see this new information in this section, since it's directly related. If you're going through the process outlined here and don't have those options, then you need to follow these instructions instead.

I think the actual instructions make sense where @dacharyc put them, but it would be good to include a summary and link to them from the troubleshooting section.

dacharyc commented 4 years ago

I was expecting to see this new information in this section, since it's directly related. If you're going through the process outlined here and don't have those options, then you need to follow these instructions instead.

Oh? My impression from these instructions is that this is a workaround for when orgs can't or won't authorize Tugboat. That's not really a troubleshooting step to fix an unexpected problem, so it's not like the scenario described here where Tugboat has previously had permissions and then repos don't appear as expected. Am I missing something that would warrant including these instructions as "troubleshooting" steps versus an alternate authorization option?

bchavet commented 4 years ago

Am I missing something that would warrant including these instructions as "troubleshooting" steps versus an alternate authorization option?

This would likely present itself as a "Missing Repository", because we can only list repos for orgs that we are authorized for as an OAuth app.

I still think it belongs where you put it. But I could see how a quick blurb in the Troubleshooting section with a link back to the full documentation for it would be helpful.

dacharyc commented 4 years ago

Am I missing something that would warrant including these instructions as "troubleshooting" steps versus an alternate authorization option?

This would likely present itself as a "Missing Repository", because we can only list repos for orgs that we are authorized for as an OAuth app.

I still think it belongs where you put it. But I could see how a quick blurb in the Troubleshooting section with a link back to the full documentation for it would be helpful.

Alrighty, good to know! I've reworked the existing explanation a little, and added a blurb with a link to the new section. Does this accurately describe the potential states & how/why they occur, @bchavet ?