GIT Pull-Requests and Reviews in TFS/VSTS

TFS or its cloud instance Visual Studio Team Services (VSTS) does have a very nice integration of GIT as a distributed version control system (DVCS). This is build into TFS since TFS 2015 and did extend with every release of TFS. The TFS Version Control backend (TFVC) is still available but my first choice when I create a new source-code repository is GIT.

How to create a GIT repo in TFS

This is a snap. Just go to your TFS / VSTS Team Project open its settings page using the gear icon in the upper left corner.

1. Open the Tab “Version Control”.
2. Press “New pository…”
3. Choose  the “Type”. Default is already GIT.
4. Give it a name and hit “Create”.
5. Your GIT repo is create within the TFS and with a default branch called master. You’ll get a page with the instructions how to clone or push it the first time.

Note: Each Team Project can have only one TFVC repository but an unlimited number of GIT repositories. One of the advantages when using GIT repos.

Set up your branches for pull-requests?

Go again to the Version Control settings of your Team Project and choose the branch you like to configure and switch to its Branch Policies:

Here you can configure the branch as you like. Check out the zoom-in of the options – quite impressive I would say but wait until you see them in action:

First you can force pull-requests to the given branch and specify a build job that gets triggered as the developer sends in a pull-request. You can configure how often the build job runs and if the pull-request gets blocked if the build job is not yet run successfully. I prefer to block it so I force everybody in the project to have builds running which includes unit-tests must passing.

Then you can configure if the pull-request must be linked with work items and if it should be blocked or not. I normally don’t block them as this gets hard for checking in fixes etc. But I active it so I will get an indicator showing me if the pull-request is linked or not. As a lead-dev I then can consider contacting the team member to ask for work items.

A really cool thing are the review options. Configuration is pretty self explaining. You’ll see it in action later on.

Finally you can configure who of your team members can or must review what part (path) of your repository. So if someone for example checks in code in a core library path maybe the lead-dev for the library should review that change too.

Now what?

With the above settings in place your team-members can not push changes directly to the master branch anymore. If they try they will get an error. Instead they have to create feature branches, push them and when done with the feature send a pull-request for this feature branch. Think of it as a “request to pull the changes from the feature branch to the target branch” (normally into the master branch). The lead-dev (or who ever is in charge) can check this pull-request and decide if he likes to integrate it the master branch.

Create a pull-request

For the demo I’ve created a little change in feature branch feature/blog_test and pushed it to the GIT server (aka GIT remote). As you see TFS will just prompt me to create a pull-request for it.

Note: If you edit a file directly in the TFS web UI and try to push it to the master branch TFS will prompt you to right away create a feature branch for you and push it include creating a pull-request. Cool!

I can eighter continue work on the feature and push more commits to it or I can create a pull-request now.

Note: You can create the feature branch our own using the GIT client of your choice or you can use the TFS web-ui to do it. For example you can create a feature branch directly from within your product backlog item / user story. This will link the feature-branch automatically with your work-item. The feature branch can also be created from the Code page. Many options to do it.

So let’s create a pull-request now by clicking the New pull request button in the TFS web-ui.

Here you can check and complete the information about this pull-request. You may wanna update the description and link it with work item(s). You also can specify the reviewers you like to get reviews from (or leave the defaults in place).

Click New pull request and the pull-request will be sent to the team and reviewers. Your job as Dev for this feature is done now. Except: you like to get the review’s done so your feature gets the DoD (Definition of Done) pass.

How to integrate the pull-requests?

So, what do have so far after the developer created the new pull-request you may ask? We still have the developers feature branch and we have a pull-request which requests to integrate this feature branch into the master branch (or how else you called your branch). TFS also fired the build job specified in the branch policies on the feature branch. The reviewer got notified that there is a pull-request ready for review. So far nothing changed on the master branch – that’s important.

Now, when you (the Lead Dev, Reviewer or Team-Member with appropriate permissions) go to the Code > Pull Requests you’ll see the pending pull-requests.

Note: On the top you have filters like Mine, Active, Completed and Abandoned. It took me a while to find them.

When you click on a pending pull-request you’ll get the details for this request:

I like that UI but its not obvious how it work when you see it the first time. So I highlighted some interesting stuff.

• In the middle column you see the pull-request header (from/to branch etc). Just below you again get filters / tab-pages. By default the Discussion tab is active but you can switch to File and Commit to check those  details too.
• On the top right you’ll see a list of indicators depending on your branch policies. Things like if merge-conflicts would happen, review-status, work-item assignements  and – if configured – the build-status. Below there are the two possible actions: Complete pull-request and Abandon. We’ll get to this in second.
• Further more on the right side you have the Review area. You see who reviewed with what feedback and you can give your own feedback. You also can leave comments in the Discuss area in the middle and even cooler you can leave your review-comment directly in the source-code view on per line base:

Now, if everything is OK with the pull-request you can Complete pull request using the button on the top left.

You’ll then get asked for some details:

Here you can finally fix up subject and description and have to nice GIT shortcuts:

1. Delete after merge will delete the feature branch after it was successfully merged into the target branch (here master). Folks pulling/syncing will get it deleted too but in case there tracking the branch locally they have to delete their local branch manually. But at least they see that it is gone on the remote server already. Nice timesaver.
2. Squash changes uses the GIT “Squash” feature to compact the history. All the commits in the feature branch will be packed into one single commit in the master branch. So we “squash” all commit together to be one single commit in the history of the master branch. It’s a matter of taste how you like to have your history look like. Again: nice timesaver.

Now the final act is to press the Complete merge button. The TFS server will fire all the GIT commands to integrate it into the master branch and – if checked – delete the feature branch. If you have continuous integration build-jobs and even continuous deployment release-jobs active the will be fired right now on the master branch – just as you they would when committing normally to the master branch.

Need a backdoor?

For a lead-dev it may be a good option to provide a backdoor around all the pull-request, review blocking for the case of an emergency. For example during a release you need to adjust something (aka quick-fix while releasing). I know, this will never happen! …but well …  yea – somehow those situations di happen – maybe it’s just me 😉

I found that on branch settings one can give right to Exempt from policy enforcement. That’s you backdoor.

Conclusion

I really like what TFS/VSTS has to offer on its GIT integration and how it all plays nicely with work planning, build- and release jobs. With the latest version this stuff is all available directly in the web UI so you don’t need Visual Studio anymore to control TFS. You can use any IDE/TextEditor and the GIT client of your choice. The rest can be done using the web UI. If you did not look at TFS for some time you might wanna give it a try again.

You can create yourself a developer account on Azure and get free VSTS (TFS online) as well as 10 free web apps and more.

Let me know what you think of this stuff.