Provide UI feedback during Git command execution

[kgryte]

Resolves #601 by providing UI feedback during Git command execution.

Overview

This PR

• introduces an overlay over the JupyterLab window during the execution of the following Git UI actions:

  • refresh
  • commit
  • branch change
  • branch creation
  • reset
  • revert commit

• cleans up the Git extension model by adding documentation, refactoring HTTP request handling to avoid error trapping, and instrumenting model actions to surface events which can then be shown in the JupyterLab status bar.

• modifies error handling when creating a branch to allow displaying error messages directly in the new branch dialog.

• adds two new extension settings to allow for customized extension behavior concerning UI suspension and status updates. This allows power users to configure extension behavior to their liking.

• adds React components for displaying a blocking modal and toast notifications.

• adds a status widget for displaying Git status updates in the JupyterLab status bar.

• performs additional minor clean-up and documentation.

This PR addresses the fact that Git actions are executed asynchronously and such behavior can result in unexpected and undesired behavior.

For example, a user could attempt to push changes to a remote server. Currently, the UI only provides feedback upon receiving a response. If a user closes JupyterLab before receiving an error response, a user could walk away believing that her changes were successfully pushed. By blocking the UI and displaying a prominent status indicator, we encourage users to wait before further action, including closing JupyterLab.

Especially given the changes introduced in #564 where a server may not respond for several seconds while waiting for index.lock files to be removed, visual feedback indicating that actions are in-progress is critical in avoiding scenarios where work is lost (e.g., a commit fails unbeknown to the user, changes are overwritten upon pull) or conflicts arise (e.g., a merge action is submitted, changes are made, and a merge action resolves, resulting in conflicts).

For example, consider the scenario where a user attempts to commit changes. Suppose the command takes 20s due to Git hooks and the command fails. During interim, the user makes changes and initiates another commit. What happens? Currently, we simply move on to the next queued command. However, a user may want to have first resolved the hook failures (e.g., linting) before executing the next commit. In fact, sometimes, you want something in history (for posterity's sake), but then want to "undo" the change subsequently. So if I commit something I want in history, it fails, but my subsequent commit succeeds, now my history is messed up. In short, we simplify everything, and reduce extension complexity, by forcing sequential operations. Otherwise, a user needs to be able to interrupt a queue, canceling any pending operations after a failure.

By blocking the UI, we effectively force the user to slow down (albeit in minor, if any, manor and without much annoyance, depending on connection speed, etc) to allow commands to fully execute before making and initiating further changes and actions.

To be clear, forcing sequential operation is likely to not be a hindrance for local development or for users on fast networks.

Screenshots

• Example overlay in light mode

• Example overlay in dark mode

• Example upon encountering an error

• Example disabling UI suspension

Notes

Other UI feedback mechanisms considered:

• JupyterLab status bar: a status bar indicator is easy to overlook and does not effectively dissuade a user from prematurely closing either the JupyterLab UI (browser tab) or the JupyterLab server before commands have finished executing. While implemented in this PR, using the status bar alone is not enough to effectively prevent users from performing actions leading to potential foot guns. Further, users are able to hide the status bar, and, thus, may never see messages indicating that the Git extension is currently working and the JupyterLab frontend should not be closed.
• widget progress indicator: restricting the progress indicator to only the Git extension side panel and not the entire UI does not sufficiently guard against lost changes and conflicts. For example, if a user is still allowed to make file changes while commands execute (e.g., git pull), then, on pull, unsaved changes could be overwritten (and thus lost) or a merge conflict could arise which would not have arisen had the user waited until the pull was complete.

Demo

Here is a Binder link for the changes proposed in this PR: https://mybinder.org/v2/gh/kgryte/jupyterlab-git/ui-feedback?filepath=examples%2Fdemo.ipynb
.

[ianhi]

It's definitely an aesthetic improvement over the current git pull/push spinner which never rendered correctly for me! and I do like being prevented from inducing conflicts :)

A few things to consider:

1. Can be flashy if the action is quick

If the action takes enough time to display the modal but is still completed quickly then it can make the screen kind of flashy. It's hard to capture in this gif because I had to up the frame rate to grab the right frames, which makes it a slow-mo gif when uploaded here.

Probably easier to see if you try yourself. I added this delay with await new Promise(resolve => setTimeout(resolve, 200)); Though, for everything I tried without adding an artificial delay this wasn't a problem.

2. Minimize the number of situations where this is necessary

Agreed that blocking the whole screen is the only surefire way to prevent the user from messing with things during a git command. However, I don't love having my full screen taken over. Could the number of places where this happens be minimized? For example:

• refresh: maybe not necessary here?
• branch creation: there is already a full screen blocking dialog used to create the branch, this could be used to block instead of spawning the modal on top of that.
• commit only needs to block the git panel. Modifying a file during an ongoing commit should be a safe thing to do.

3. make it dismissable?

If something like a push is taking a long time it might be nice to include an option to dismiss the dialog similar to the current git push/pull ui that uses the jupyterlab/apputils Spinner. I'm imagining that I need to switch what I'm working on and I've done bad thing by committing several very large files so pushing will take awhile. Here not being allowed to switch folders to whatever else I want to work on is potentially frustrating.

4. Use the status bar as well

For scenarios like the push you described, having a confirmation of success on the status bar could be nice in order to provide firmer confirmation of success than just the modal going away.

[fcollonval]

@kgryte I like the animation but it should definitely not block the all application.

For all softwares I know that integrate VCS, none is blocking the UI when carrying out git commands. And this is clearly what I would expect from this extension (for instance I hate the current modal for pulling and pushing that block me on background synchronization tasks). Therefore the overlay should not expand outside of the Git panel. But then come the question, what if the panel is hidden. So I endorse too the idea of having feedback thanks to the status bar.

[ianhi]

@kgryte I tried it out and this PR causes me to be unable to commit:

If I switch to the master branch and use the same repo then I don't have this issue. I use SSH for git credentials if that matters.

Otherwise I've really come around to it. It looks nice and the removal of footguns is definitely positive.

2

yes, we want to show a progress indicator because, as a user, I want to know that everything is up-to-date before I continue editing

makes sense. This actually made me realize that I miss having any feedback when I refresh the jupyterlab filebrowser.

3
Thanks :)

4
As for the Status bar updates I've suddenly arrived at second thoughts. The changing every 3 seconds in the bottom left corner of vision is pretty distracting. With the nice toast notifications you made maybe this isn't necessary? Or perhaps refresh could be excluded from status bar updates. could we prevent refresh from triggering a status bar update?

[kgryte]

@ianhi Thanks for trying it out! Will investigate the issues you mentioned above and circle back.

[ianhi]

One other thought that may have a bad hassle/benefit ratio:

Could the modal be made to display only after the command has been running for some time that is short for humans but long for computers? i.e:

• Run command
• wait 200ms
• if command not finished
  • spawn modal for minimum of 1 second
• continue as normal

The idea being to maintain protection against conflicting commands while reducing visual interruption. Though maybe this would just have the effect of making the extension seem laggy which I think would be worse.

[kgryte]

@ianhi

• Re: 1. Tracked down the commit bug. Should be fixed.

• Re: 4. We could exclude refresh from the status bar; however, this is also "useful" information, as it provides feedback when changing the refreshInterval setting and clues in the user that "stuff" is happening (e.g., HTTP requests) which might be costly (e.g., AWS bill). A user might see the status bar updating and decide to decrease the refresh interval; however, they may not be aware that that will mean the UI becomes laggy (e.g., switching a branch might take a while to appear in the UI, especially if done outside of the JLab UI, such as at the command-line).

  If other reviewers object to including the refresh status updates, I can remove; but, for now, I lean toward keeping them in. This PR allows disabling Git extension status bar updates altogether via the displayStatus extension setting. So, if toasts are sufficient, then a user can just disable status updates.

• Re: delayed modal onset. I think this will make the UI seem laggy, so I am not inclined to introduce such a modal lag.

[kgryte]

For those interested, here is a Binder link for viewing the changes proposed in this PR: https://mybinder.org/v2/gh/kgryte/jupyterlab-git/ui-feedback?urlpath=lab/tree/examples/demo.ipynb
.

[kgryte]

@telamonian Should be ready for review now that the commit bug is resolved.

[fcollonval]

Thanks @kgryte for this big, yet modular 😉, work.

I only have one concern with this change. Up-to now, the model has close to a service for git commands. But with this, this is definitely no more the case as it increases the link with the UI.
So it would be nice to extract a service for the git commands after this is merged.

As example of the need for a service, I can point to that repository: https://github.com/fcollonval/jupyter-project

[kgryte]

@fcollonval Thanks for the review!

Re: model-UI coupling. I don't believe these are more coupled than before this PR. The PR simply adds "logging" which could be directed to a file, to a UI, or to anywhere. The model is still decoupled; the change introduced by this PR is simply to afford model consumers the opportunity to listen in on what the model is doing if they so choose. Here, the PR opts to take the information and bubble up to the end user, but this is not required.

In general, there has been a long standing request by our clients to provide more insight into what the Git extension is doing when performing various operations/tasks. This PR simply moves us a couple steps in that direction. :)

[kgryte]

@fcollonval Should be good to go!

[kgryte]

@telamonian @fcollonval Are we able to move forward with this PR? :)

[fcollonval]

I'm working on this one to rebase and merge. Sorry for the delay @kgryte.

[fcollonval]

Merged manually in dafc400

[kgryte]

Thanks @fcollonval!