[Feature NDDB] - Notification of Diverging From Default Branch

[nerdneha]

Goal

As a user, when I am working on my own branch, I want to know when a relevant branch (ex: master) has new commits so that I can merge those changes in as soon as possible to avoid conflicts over time and so that I don't have to break my workflow to check if there are updates.

Background
Built upon the Compare Branch feature that's about to land in 1.2.

Solution

This issue tracks all the work needed to be done around this feature. See the task list for a breakdown of what needs to be done.

The following is a high-level overview of the solution. Implementation-specific details will be placed in the appropriate sub-issue and/or pull request.

History Tab

• Desktop will try to infer what base branch should be used to compare with the current branch, so the user won't have to perform any setup to use the feature
• If the number of commits behind is different from the last time Desktop checked, a blue notification dot will be placed on the History tab.
• To provide additional context for the notification, a banner will be rendered between the History tab and the compare branch selector; The banner will include the info on the number of commits the current branch is behind and two call-to-action buttons: Merge and Compare
• If the Merge button is clicked, the Merge dialog will appear with the base branch preselected
• If the Compare button is clicked, users will be taken to the compare view
• The notification dot will be cleared if the user clicks on the History tab; the banner will be persisted until dismissed through one of the actions or being dismissed

Changes Tab

• To avoid confusion, the notification dot will be replaced with a badge that contains the number of changes to be committed (pulled from scope, see Related Issues section below)

Alternatives Considered

• @donokuda and I spoke about potentially adding a bit of context to the notification dot such as the number of commits the current branch is behind the base branch. We agreed we can iterate to that point if we decide to move in that direction.

Risks

Risk	Mitigation
We scrap the current design for the Compare Branch feature	Focus on making implementation UI/UX agnostic

Mockups

A breakdown of the UI for some of the newer elements:

Testing

User Testing Strategy

We need to actors to test this feature:

• Desktop team member
• Mona (the user)

Setup

1. Create repository, test, on GitHub
2. Clone test using Desktop
3. Push a file, file.md to master
4. Ask Mona to clone test and create a new branch, dev, using master as the base branch

Testing

The testing of this feature requires us to get the timing right as we are trying to simulate multiple actors working on a branch concurrently.

Since there are 2 call-to-action buttons on the notification banner, I’ve split the testing strategy. The steps that are common to each flow will be listed under the section, Shared flow. Steps in bold only need to be performed once.

Shared flow

1. Have Mona make some changes to file.md
2. Push another commit to master(performed in the background)
3. We expect Mona to see the blue dot on the History tab after auto-fetching completes (have Mona perform a manual fetch if necessary)
4. Wait to see if Mona notices the notification
5. Have Mona click on the notification
6. We expect Mona to notice the notification is no longer visible
7. We expect Mona to notice a banner with some details about why she received a notification
8. Ask Mona what she thinks the banner means (we're looking to see if the banner provides enough context)
9. Ask Mona what she expects dismissing the banner to do
10. Have Mona to dismiss the notification
11. We expect Mona to use the x located in the top-right corner of the banner
12. Have Mona make some changes to file.md
13. Push another commit to master (performed in the background)
14. Have Mona click on the notification

Compare flow

1. Ask Mona what she expects clicking the Compare button to do
2. Have Mona to click the Compare button
3. We expect Mona to see that the notification banner has disappeared
4. We expect Mona to recognize that the app is in the branch comparison view with the base branch preselected as the compare branch;
5. We expect Mona to see 2 commits in the Behind tab
6. Ask Mona what she expects clicking the Merge button will do
7. Have Mona click the Merge button in the compare branch view (RBB)
8. We expect Mona to notice the message saying she’s up-to-date with the base branch (RBB)

Merge flow

1. Ask Mona what she expects clicking the Merge button to do
2. Have Mona click the Merge button inside the banner
3. We expect Mona to notice the Merge dialog appears with the base branch preselected
4. Have Mona perform the merge

Tasks

• Draft user testing strategy (co-ordinate with desktop/qa?)
• Get approval for solution from desktop/design
• Add a feature flag - Create a feature flag for NDDB #4765
• Get logic in place to infer what the compare branch should be - Infer what branch should be used as the compare branch (NDDB) #4766
• Show blue dot on History tab when updates are detected on the base branch- Display a notification on History tab when the base branch moves ahead of the current branch (NDDB) #4767
• Build banner that displays some context about the notification and two call-to-action buttons - Add a banner component to complement the notification displayed when the base branch moves ahead of the current branch (NDDB) #4768
• Add functionality to make Compare button show the Compare Branch view with the compare branch preselected - Render the compare view when compare button is pressed (NDDB) #4808
• Add functionality to show Merge dialog with the base branch preselected - Show the merge dialog when merge button is pressed (NDDB) #4809
• Add metrics - Add metrics (NDDB) #4883

Related Issues

• Analytics for feature - https://github.com/github/analytics/issues/520
• Change notification on Changes tab to a badge - Change notification dot on Changes tab to a badge #4772

[iAmWillShepherd]

I'm thinking we could capture whether a merge is executed after the notification dot is placed, but I'm unsure how valuable that would be without also capturing the amount of time that passes from the notification appearing and the merge action taking place.

@desktop/analytics Do you think capturing this metric is valuable? Are there any other metrics we want out of this?

[telliott27]

@iAmWillShepherd sorry I'm late on responding here. I think counting the number of merges that happen within X minutes (say 15? 30?) of the notification dot being placed would be useful. Unfortunately, since we are collecting aggregate stats for an entire day, calculating the amount of time that passes between the notification dot and a merge doesn't really fit into that schema.

[nerdneha]

what do we think about making the user testing strategy collapsible so that the info exists but the issue doesn't feel too large? i saw @meaghanlewis do this and i kind of love it...and will use this forever (i saw her do it here: #4734)

[iAmWillShepherd]

@donokuda and I did some user interviews last week and I wanted to document some of my observations as well as offer potential solutions:

1. The notification dot is not very noticeable
   • Only one of our users noticed it, but they were unsure if it was there to begin with. Another user clicked the tab that contained the notification, but admitted to not realizing it was there because of committing a change. I think scrapping a dot and just changing the color of the tab would make it more obvious that something has changed.
2. The banner is good, but there is room for improvement
   • Everyone was able to intuit that the banner implied there was additional work to be done.
   • The proximity of the banner to the Branch Compare Selector and History View did cause a bit of confusion. One person said that it wasn't super clear that the number of commits mentioned in the banner were different from the commits shown in the History View. I think changing the background color of the banner and only showing either the banner or the Compare Branch Selector would help differentiate it from the Compare Sidebar.
   • One of our interviewees had the awesome suggestion that we show the branch and the remote.
3. General observations not 100% related to this feature
   • One person expected the Compare button to show a diff of the changes

My suggestions are in bold

[donokuda]

Based on observations from a couple of usability tests and feedback from @iAmWillShepherd and @niik, here's where I landed with the notification banner (I'll be using @iAmWillShepherd's feedback as a jumping point for discussion):

• The proximity of the banner to the Branch Compare Selector and History View did cause a bit of confusion. One person said that it wasn't super clear that the number of commits mentioned in the banner were different from the commits shown in the History View. I think changing the background color of the banner and only showing either the banner or the Compare Branch Selector would help differentiate it from the Compare Sidebar.

In order to prevent people from associating the notification banner and the list of commits below, I updated the background color as well as added some padding/margin to visually differentiate the two elements further.

I added an octicon (via @niik's suggestion) to help communicate that the banner is more informational.

• One of our interviewees had the awesome suggestion that we show the branch and the remote.

I'm onboard with this. master and origin/master generally mean the same thing in Desktop; if we update the branch text to origin/master, then we should make sure that is the actual branch being compared against.

• One person expected the Compare button to show a diff of the changes

I updated the "Compare" button to say "View commits" to better describe the action that's supposed to happen after someone clicks that button.

Only one of our users noticed it, but they were unsure if it was there to begin with. Another user clicked the tab that contained the notification, but admitted to not realizing it was there because of committing a change. I think scrapping a dot and just changing the color of the tab would make it more obvious that something has changed.

I'm a little hesitant in trying to make this feature more noticeable, since it might take attention away from more important features and workflows. If we determine that people cannot find the feature, then we should continue with usability tests to see where they naturally search around in the app.

[nerdneha]

@donokuda these look like great edits! thanks so much for taking some time to get some initial feelers @iAmWillShepherd and @donokuda 🌟!!

[shiftkey]

@nerdneha @iAmWillShepherd anything left on this tracking issue, or can we close it out?

[iAmWillShepherd]

...anything left on this tracking issue...

@shiftkey yes, the PRs related to metrics have not been merged yet so there is still one open issue. We can close this once we ship.

[shiftkey]

I'm 👎 on having lots of duplicated noise about the leftover work for 1.3.0, so I've moved the pending site update work to my release checklist https://github.com/github/releases/issues/191#issuecomment-407440469