Tracing Work: Conception to Completion
Risk is expensive. Things are risky when they are unknown. The best way to make those unknowns become known, is to figure out where you’re going and where you’ve come from. Luckily, Azure DevOps lets you keep track of work from beginning to end easily.
Epics, features, user stories and tasks are terms we’re all familiar with and Azure DevOps lets us quickly build, organize and query all of those items to keep track of what we’ve done and what is left to do. Sometimes, just having those pretty cards and swim lanes isn’t quite enough. It takes diligence in requirements gathering, clarity of expectations and a culture of tracking all aspects of work to really shine in any project.
A user story is, in general, is a first person statement declaring some type of need. It’s usually fine if it’s a little vague and encompasses more than one subject. It can even be a high level flow from one state to another. User stories are important to understand an overall view of the task at hand. Acceptance criteria, however, are the real meat and potatoes of the value we’re adding to an application. Acceptance criteria defines a definition of completeness. Once all the criteria are met, the needs of the user story should be fully captured and the task completed.
Acceptance criteria is quite analogous to test driven development. In test driven development, you write your test cases first and take pause to think about what you’re trying to accomplish with your code. Once your test cases are adequate, you write your feature code and keep working until all your test cases have passed. Once all the tests pass, your feature is considered complete, assuming you’ve adequately covered edge cases. The same kind of pause and deep thought should be put into acceptance criteria. The requirements should be concrete, clear and edge cases should be considered. If any question of the functionality is brought to light, it should be addressed immediately, before being put into any kind of sprint or other action.
Commit tracking is the act of linking code commits to work items. Doing this is important, because then you can follow the code through to the work items to make sure that features are moving along as intended. It also lets you go back and find which work items are affected if there is a problem in the system. If there is a work item that has been in the sprint for a long time and no work has been done on it, you can address it. If you have no tracking of code to work items, you won’t know if something is being worked on, or what items are impacted due to a malfunction.
If you keep your code repositories in Azure DevOps, setting up commit tracking is a breeze. Simply go to your Project Settings, in the bottom left of your Azure DevOps project:
Then, under the “Code” heading, choose repositories:
From there, you’ll see your list of repositories and a new blade to the right that says, “Security for all Git Repositories” with an “Options” tab. Choose the repository you want to set work item tracking up in and click the “Options” tab:
In that screen, find the “Work item management” switch and turn it on.
Now, when you’re entering your commit messages, just put a hashtag and the work item number the commit is for in there, and it will automatically link your commit to that work item. For example, if you had a task number 1928, your commit could be something like, “Fixing a timeout issue for logging in #1928” and once the commit was pushed to the repository, that link would show in the task.
Another option is to enforce branch policies with Azure DevOps. You can make it so that the branch will only allow commits that are linked to valid work items. At the time of writing this, you need to determine policies on each branch individually and cannot set a default prototype branch for new branches to derive from unless you do some special Azure Function things that are out of scope for this post. This can make it annoying if you’re doing a lot of small feature branches, but here is how to enforce that policy for completeness.
Step one is to go to your list of branches:
Next, select the ellipses to show more options for the branch you want to define the policy for and choose the “Branch policies” option.
That will bring you to the policy for that branch and from there, make sure “Check for linked work items” is checked and choose the “Required” radio button to enforce the linking on commits.
Tracing your work is important. It reduces risk, helps to understand defects and allows a transparency to work being done that lets everyone feel more confident about the work being done on time and on budget. While turning on commit tracking is a great first step, isn’t quite enough. A culture must be formed around developing clear acceptance criteria for features and make sure those criteria are met when developing those features. Once a good work flow is formed things like tracking work lead time and sprint planning will become simple and your project will be more successful.