If you’re a developer working on a team that uses Git, you’re probably using some form of topic branching to isolate your work.  If you’re using any of the Agile tools in Visual Studio Team Services, you probably also have a bug, task, or user story that’s tracking your development work.  Until recently, the best way to keep these items related was to link your commits to your work items using a #ID mention in the commit message.  VSTS has some great new features that can make it much easier to track the relationship between your code and work.

New Development section on work items

In the new work item form, we’ve added a new “Development” section that surfaces the related commits, branches, and pull requests.  This new section makes it easier than ever to see the links to the code that is associated with your work – and drilling in to the details of a commit or the feedback in PR is a click away.

While displaying links more prominently is certainly useful, the Development section is more than just a place to show links.  Using the context of the linked items (or lack thereof), the section provides links to help developers take action.  I think an example works best to show the various capabilities…

Create a branch for your work

Let’s start at the beginning – you’ve been assigned some work, and you’re reviewing the story to understand the scope of your next task.  This story hasn’t yet been linked to any code, so there’s an action link to Create a new branch.

Clicking the link shows the Create Branch dialog, and the Work Items to Link section automatically includes the work item.

Once the branch has been created, the browser opens the new branch in the Code Explorer, and the branch is ready for development.  If you’ve already cloned the repo, you’ll need to fetch and checkout the remote branch locally before you can start work.  Visual Studio makes it easy to do this from the Branches page.

Checking out the new branch is also easy from the command line.

git checkout -b newbranch origin/newbranch

In our example, the exact command would be:

git checkout -b users/mateo/cache-perf origin/users/mateo/cache-perf

When changes are committed to the local branch and then pushed to the server, the Development section will show when the branch was last updated and who made the changes.

Creating a pull request

Now that our branch has some changes, we can create a pull request.  In addition to the existing ways to create a PR, the Development section provides an action link to Create a pull request when a branch is linked to a work item.

Clicking the link jumps into the Create Pull Request experience with the source branch prefilled and the work item automatically included in the Related Work Items section.  By creating the link from the branch to the work item, the Create PR experience is able to find our work item and automatically include it.  If the branch had commits that were linked to other work items, those work items would be included here as well.

Once the PR is created, the Related Work Items section shows the work items that are linked to the pull request.  More work items can also be linked from this section after a PR is created.

If we revisit the work item, we’ll also see that the Development section shows the link back to the PR.

Completing a pull request with a merge

When the review of the PR is complete and policies are passing, it’s time to merge.  In the Complete Pull Request dialog, the default description for the merge commit will include a list of the work items associated with the pull request.  This is useful for anyone viewing the commit history in the future to know which work items are related, no matter what tool they’re using to view history.

After the PR is merged, the related work items will be automatically linked to the merge commit.  The commit details view will show all of the linked work items.

The Development section will show the PR (with the latest status) and the newly created merge commit.

Linking to existing artifacts

We just saw how the new linking experiences work when starting work on a new branch – but what if you already have a branch that you want to link to a work item?  The work item form still has a Links tab where links to branches, commits, and pull requests can be created.

Some developers find that they would rather link their work items as part of their development process.  In Visual Studio, the Related Work Items section on the Changes page can be used to create links from commits to work items.

And those that prefer command line can always use a #ID mention to link a commit.

git commit -a -m "Fixing bug #42 in the web client"

No matter how you prefer to link your work to your code, those work items will be automatically linked when creating a PR.  And if you ever need to remove a link, that’s easy too.

All of these new features make the traceability between work to code better than ever.  In the near future, we’ll have even more features to help trace your commits to branches, builds, and pull requests.  Stay tuned!