Add project create modal for repairing the repository listing

[agjohnson]

This is a stronger UI that adds a little more content around why the
user might need to resync/reconfigure permissions. This isn't yet as
aggressive as it might need to be, it's just the scaffolding for the UI
and experimenting a bit more with the UX and feedback to the user.

• Fixes Project: add GHA directions to project creation #620
• Requires Use context data instead of one off template tags readthedocs.org#12506

[agjohnson]

Here are the changes as of ca9c2ea:

Screencast.From.2025-10-03.17-57-53.mp4

[agjohnson]

There are some UX issues that were distracting me, they are fairly significant but I am putting these off until later:

• https://github.com/readthedocs/readthedocs-corporate/issues/2046

[humitos]

This is going in a good direction.

The modal is still not clear about what is the action I should take. As a user it's hard to know if I need the first or second option from the modal --but I think it's what we have for now until we know how to do detect the GH's user configuration.

I'm not sold on the UX here. The popup looks pretty prominent and I think that's OK. However, I don't like the logic to avoid showing the popup once it was hidden. It's pretty easy to miss the popup by doing hover on it. I would start by removing that logic first.

Peek.2025-10-06.12-58.webm

Also, I'm not sure if a popup is the right UI element here. Can't we just add the popup content as a result in the list? I mean, when we show No matching repositories found we can add the button to show the modal there.

[ericholscher]

The modal is still not clear about what is the action I should take. As a user it's hard to know if I need the first or second option from the modal --but I think it's what we have for now until we know how to do detect the GH's user configuration.

I think this is the big thing. We should probably try to have some clarifying text on which button will actually solve the issue, if we can. When I see those 3 options, I'm mostly just confused about what will actually solve my problem. Perhaps I should just press all 3? 🤷

I'm not sold on the UX here. The popup looks pretty prominent and I think that's OK. However, I don't like the logic to avoid showing the popup once it was hidden. It's pretty easy to miss the popup by doing hover on it. I would start by removing that logic first.

Agreed on the popup going away being bad. We should at least have some kind of button that is always available once it's been triggered, because hovering and then losing it is super frustrating.

Also, I'm not sure if a popup is the right UI element here. Can't we just add the popup content as a result in the list? I mean, when we show No matching repositories found we can add the button to show the modal there.

I think having it in the list when no matches makes sense, but there's likely also cases where there are some matches, but not the one you want. So we need to account for that as well.

[humitos]

Looks better. Can we avoid hiding the popup on hover? It's pretty frustrating UX to me. It's pretty easy to hover the popup and "un-hover" it by mistake while trying to click on "Repair" button.

Peek.2025-10-07.15-43.webm

[agjohnson]

The modal is still not clear about what is the action I should take

I'd like to get here ,but I don't think this is possible now. We can't suggest a fix because we can't detect what the problem is -- oauth approval in a GH organization can't be detected at all even. I'd rather give the user most options in one place for now.

Also: this UI looks different for users that have just a GHA account attached. Having both GHA and OAuth account attached the modal will have more troubleshooting options.

but I think it's what we have for now until we know how to do detect the GH's user configuration.

Yup, this is what I'm waiting for. This UI is a first step to improving the troubleshooting steps.

However, I don't like the logic to avoid showing the popup once it was hidden. It's pretty easy to miss the popup by doing hover on it. I would start by removing that logic first.

There isn't a configuration option for avoiding hover out on popups, but I might be able to intercept the event. I want to retain the logic to show and reshow the popup though, I feel it's bad UX without this.

We should probably try to have some clarifying text on which button will actually solve the issue, if we can.

This UI is already getting text heavy. I'd like to get this in front of users before optimizing copy much more.

Overall I'd rather we are able to detect what to point the user towards. But also, note above re GHA and GH Oauth accounts -- there are more options in your list because you're connected to both GHA/Oauth, we expect most users to not have both connected.

Can't we just add the popup content as a result in the list?
I think having it in the list when no matches makes sense

I already tried this. It worked okay for when there were no matches and didn't work well at all when there were matches. I've been -1 on this for that and prefer the popup. There might be something better than the popup, but I'd like to just get this in front of users.

[agjohnson]

There isn't a configuration option for avoiding hover out on popups

When I added the popup, I tried a couple things to avoid this but nothing quite worked. The onHide event is there, but it breaks hiding on body click events or calling popup('hide').

In 4ae8cb8 I found I could add a long hide delay to mostly mimic this though. This only effects hover focus out, the popup can still be closed by the popup('hide') behavior and on body click close without introducing a delay:

Screencast.From.2025-10-07.16-09-55.mp4

I feel this is enough to get started with and an improvement to what's there now. Next up would be tuning documentation. I feel our docs should probably be where we provide in depth troubleshooting to supplement this UI being lightweight, instead of bloating this UI much more.

[humitos]

The delay in the popup looks great! Thanks for taking my feedback into consideration.

I think we are ready to move forward and come back to this modal UI once we can detect the issue.

[stsewd]

Also: this UI looks different for users that have just a GHA account attached. Having both GHA and OAuth account attached the modal will have more troubleshooting options.

BTW, the current implementation forces users to use the new integration to import projects once they have started using it (linked a project to the GH app).

Also, as Eric mentioned, users may still get results in the search, but not from the repos they want, I think it would be helpful to have another way to trigger that popup, like from a help link on the side.

[agjohnson]

users may still get results in the search, but not from the repos they want,

This is part of my original implementation already, I don't think my screencasts above show this though. There are two ways the popup shows:

• After a query results in 0 results
• After 3 queries result in 1 or more hits

Queries are essentially keypress events, so this feels fairly tuned. The only case that isn't covered is the user making only 1 or 2 keypress event searches that have results and then stopping.

I'm not opposed to a button or help link if it feels necessary later, just don't think it's required yet.

BTW, the current implementation forces users to use the new integration to import projects once they have started using it (linked a project to the GH app).

How/where is this enforced currently? Seems like we could at least skip some repair directions for a good chunk of users that just have GHA and GitHub OAuth connected at least.

If a user has GitLab/Bitbucket/manual integrations, the user should still be able to use these for project creation though. So the logic will be close to what is here now, but maybe with some exceptions for GitHub Oauth + GHA combinations.

[stsewd]

How/where is this enforced currently? Seems like we could at least skip some repair directions for a good chunk of users that just have GHA and GitHub OAuth connected at least.

https://github.com/readthedocs/readthedocs.org/blob/acaf4e017736e33bbdcd2b61673d9d748f59e23d/readthedocs/oauth/querysets.py#L67-L71