[Feature NDDB] - Notification of Diverging From Default Branch

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 - #4765
• Get logic in place to infer what the compare branch should be - #4766
• Show blue dot on History tab when updates are detected on the base branch- #4767
• Build banner that displays some context about the notification and two call-to-action buttons - #4768
• Add functionality to make Compare button show the Compare Branch view with the compare branch preselected - #4808
• Add functionality to show Merge dialog with the base branch preselected - #4809
• Add metrics - #4883

Related Issues

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

[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

[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: https://github.com/desktop/desktop/issues/4734)