Azure DevOps History Diff

• Introduction
• Basic installation and requirements
• Details about the new "History" tab
  • Basic functionality
  • Configuration
    • Filters
    • Limiting the maximum width of the tiles
    • Showing only unchanged lines
• On-premise installation (Azure DevOps Server)
  • Uploading the extension to Azure DevOps Server
  • Enabling/configuring the history tab for work item types
    • Installation for the "Inheritance" process model
    • Installation for the "On-premises XML" process model
• Cloud installation (Azure DevOps Services)
  • Installation for the "Inheritance" process model
  • Installation for the "Hosted XML" process model
• Updating the extension
• About authentication requests in Firefox
• Future ideas

Introduction

The standard history tab of work items in Azure DevOps (ADO) shows only the entire old and new values of each field, without highlighting the actual changes within it. This makes spotting the difference very hard for fields that usually contain a lot of text; most prominently, the standard "Description" and "Repro Steps" fields as well as the comments. This extension adds a new tab to work items that shows the full history of every field, while computing an appropriate diff for each one. Optionally, the user can filter out uninteresting fields (e.g. related to work logging) and show only the changed lines in long texts.

If you like the extension, please give it a star on GitHub and rate on the Visual Studio marketplace!

The left image shows the default ADO history, while the right depicts the history as shown by the extension: Changes to the text are much easier to spot.

Basic installation and requirements

Installation:

• Via the Microsoft marketplace.
• If you are using the on-premise Azure DevOps Server, you can also download the extension's vsix package from the releases here on GitHub and install it directly without using the marketplace.

Please see the sections below for more details on how to install the extension.

Requirements:

• Azure DevOps:
  • On-premise: Azure DevOps Server 2019, 2020 or 2022. (Tested with 2019.1.2, 2020.1.2 and 2022.1.)
  • Also supports the cloud variation Azure DevOps Services
• Users should use a reasonably recent browser (year >2020). Tested with Edge, Chrome and Firefox.

Change log:
For release notes, please visit the releases page.

Building it yourself:
If you want to build the vsix package yourself (also compare the official Microsoft documentation):

• Get the source code from the extension's GitHub repository.
• Execute npm install -g tfx-cli somewhere to install the extension packaging tool (TFX) globally.
• In the code's main directory, execute:
  • npm ci to get the dependencies.
  • npm run build to create the vsix package (optimized release version) or npm run build-dev (non-optimized development version).

Inspecting the vsix package:
If you want to inspect the contents of the vsix package e.g. for security auditing purposes, it can be extracted using tools such as 7-zip. Note that the html and javascript files have been minimized and merged via webpack to improve loading times. So I suggest reading the original source from the GitHub repository instead. You can then build the vsix package yourself (npm run build, see above) and verify that the content of your manually produced vsix package is the same as in the released vsix package (from the marketplace or GitHub releases page).

Details about the new "History" tab

Basic functionality

The extension adds a new tab called "History" on the work item form. It does not modify the existing ADO history page because this is not possible with an extension to the best of my knowledge.

When opening the new "History" tab, the extension gets all previous changes of the work item and the comment history via the Azure DevOps REST API. For HTML-based fields (e.g. the "Description" field, comments, or custom fields of type "Text (multiple lines)"), the extension uses a custom fork of htmldiff to compute a diff that is aware of HTML elements. String fields are diffed as ordinary strings (actually, using the same library, but with special characters escaped). For all other field types, computing a diff makes no sense and the entire old and new values are shown directly. The extension also shows the comments of new relations/links, but only the newest version of the comment text. ADO does not provide an API to query the history of relation/link comments (in contrast to the work item comments).

Removed/old fragments are highlighted with a red background, new fragments with a green background. The extension is aware of the dark mode theme and uses appropriate colors. Note: Changing the theme in Azure DevOps (light to dark or vice versa) might not immediately change all colors. The page should be reloaded after changing the theme.

Configuration

Using the "settings" button in the top right corner of the history tab, users can configure a few things. All settings are stored per user on the server using ADO's data storage facilities.

Filters

Users can filter out fields that are uninteresting to them, such as work logging related fields or fields used by scripts for housekeeping purposes. The field names as shown in the history are matched completely by default and case-insensitively. Note that a * wildcard can be used to match any number of arbitrary characters. For example, description, Desc*, *SCRIPT* and *tion will all match the field Description. To make entering fields easier, the fields of the currently active work item can be selected from a dropdown (Edge and Chrome show a dropdown button directly, Firefox users need to double click or use the arrow keys to show it).

The configuration dialog also allows to disable all configured filters without deleting them; the intention is to allow the user to temporarily view the full history without losing the configured filters.

Limiting the maximum width of the tiles

Users can choose to limit the maximum width of the history tiles. This option is available in the configuration dialog and helps improve readability on very wide screens.

Showing only unchanged lines

The left button in the top right corner of the history tab allows to toggle between showing all lines, or only the changed ones. If you choose to show only changed lines, N >= 0 additional lines above and below each change is displayed. The value of N can be configured in the settings dialog (right button in the top right corner). A value of N=0 means that just the lines containing the changes are shown. Note that for values N>0, the extension merges consecutive "context sections". They are also merged when the distance between the sections is less than approximately one line.

On-premise installation (Azure DevOps Server)

Uploading the extension to Azure DevOps Server

See the official Microsoft documentation. In short, you have two options:

1. Option 1: Direct installation from the marketplace.
   In the web interface of your Azure DevOps Server, go to Collection Settings → Extensions → Browse marketplace (in the top right corner) → search for "Sedenion.HistoryDiff" to find the extension and click on it → Get it free → select the target collection from the drop down list → hit Install → Proceed to collection.
2. Option 2: Manual upload of the vsix package.

   1. Download the vsix package either from the Microsoft marketplace or the releases here on GitHub. Both host identical files. Then in the web interface of your Azure DevOps Server, go to Collection Settings → Extensions → Browse local extensions (in the top right corner) → scroll down and select Manage extensions → then Upload extension (top right corner).

   2. Afterwards, on the Browse local extensions page, the History Diff extension should have appeared. Click on it → Get it free → select the target collection from the drop down list → hit Install → Proceed to collection.

You need to do this once per collection. Also, simply uploading the extension is not enough if you use the "On-premises XML" process model. See the next chapters for more information.

Enabling/configuring the history tab for work item types

The next steps depend on the process model your ADO collection employs. There are three process models in ADO:

• The "Inheritance" model, which allows to configure work items in the web frontend. This is the default for new collections in Azure DevOps Server. It is also the only choice in Azure DevOps Services (apart from organizations that used the data migration tool).
• The "On-premises XML" model, which uses the witadmin tool to perform the configuration.
• The "Hosted XML" model, which applies only to the cloud variation "Azure DevOps Services", but not the on-premise Azure DevOps Server. It is only available for organizations that used the data migration tool.

If you are unsure which process model your on-premise installation for Azure DevOps Server employs: In the web frontend of ADO, go to Collection Settings → Process. If you see the Upload process template button below the "All processes" and "Processes" texts, you are using the "On-premises XML" process model, and otherwise the "Inheritance" model.

Installation for the "Inheritance" process model

Basically, there is nothing else to do. The new "History" tab should appear automatically on all existing and new work item types.

The new tab can be changed per work item type in the work item type's configuration page: Go to Collection Settings → Process → click on the desired process → click on the desired work item type (e.g. "Task"). In the opening page you can rename, move and hide the "History" tab. Note that changes are not allowed for the default processes ("Basic", "Agile", "Scrum", "CMMI"). You need to create and use an inherited process for this.

Installation for the "On-premises XML" process model

The "on-premises XML" process model uses the witadmin tool.

1. To run the tool, open a command prompt where Visual Studio is installed (or alternatively the developer command prompt for Visual Studio). For details, see here.

2. Export the definition of a work item type to XML:

   witadmin exportwitd /collection:collectionurl /p:project /n:typename /f:filename
   

   The typename is the name of the work item type, e.g. Bug. The filename specifies the destination file; it should end with an .xml extension. Run witadmin exportwitd /help for additional details.

3. Open the created XML file in a text editor and search for "Work Item Extensions". It should look similar to this:

         ...
         </Layout>
         <WebLayout>
           <!--**********************Work Item Extensions**********************
   
   Extension:
   	Name: HistoryDiff
   	Id: Sedenion.HistoryDiff
   
   	Page contribution:
   		Id: Sedenion.HistoryDiff.historydiff
   		Description: Tab to show the history of work item fields with proper diffs.
   
   Note: For more information on work item extensions use the following topic:
   http://go.microsoft.com/fwlink/?LinkId=816513
   -->
           <SystemControls>
             <Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" />
             ...

   If you have multiple extensions installed, the XML comment might list additional entries. Below the XML comment, add

   <Extensions>
     <Extension Id="Sedenion.HistoryDiff" />
   </Extensions>

   It is important that you add it before the <Page> element further down. For example:

   ...
   <!--
   ...
   Note: For more information on work item extensions use the following topic:
   http://go.microsoft.com/fwlink/?LinkId=816513
   -->
           <Extensions>
               <Extension Id="Sedenion.HistoryDiff" />
           </Extensions>
           <SystemControls>
             <Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" />
             ...

4. Import the modified XML file back into ADO:

   witadmin importwitd /collection:collectionurl /p:project /f:filename
   

   where filename is the path to the modified XML file.
   Afterwards, the new "History" tab shows up in work items of the type typename specified in the second step above. You need to do this for every work item type which should show the new "History" tab.

5. Optional: You can change the position and the name of the "History" tab by adding

   <PageContribution Id="Sedenion.HistoryDiff.historydiff" Label="New History Tab Name"  />

   in the XML file after the <SystemControls> node at the desired position. In the following example, the new tab is inserted between "Page A" and "Page B" with the name "Awesome History":

   ...
   <!--
   ...
   Note: For more information on work item extensions use the following topic:
   http://go.microsoft.com/fwlink/?LinkId=816513
   -->
      <Extensions>
          <Extension Id="Sedenion.HistoryDiff" />
      </Extensions>
      <SystemControls>
        ...
      </SystemControls>
      <Page Label="Page A">
        ...
      </Page>
      <PageContribution Id="Sedenion.HistoryDiff.historydiff" Label="Awesome History"  />
      <Page Label="Page B" LayoutMode="FirstColumnWide">
         ...
      </Page>
      ...

For further details on adding extensions to work item forms, see here. You might also want to look up the general manual for on-premises XML process customization and the XML element reference (search for "extension" there).

Cloud installation (Azure DevOps Services)

Installation for the "Inheritance" process model

Most "Azure DevOps Services" instances should use the "Inheritance" process model. To install the extension in this case, go to the Microsoft marketplace and click "Get if free". You then need to select your organization and hit "Install". That should be everything you need to do. Please see Microsoft's official installation instructions for more details.

The new "History" tab can be configured as explained above in the chapter 'Installation for the "Inheritance" process model' of the on-premise installation instructions.

Installation for the "Hosted XML" process model

The "Hosted XML" process model is only available for organizations that used the data migration tool. The installation of the extension should be the same as for the "Inheritance" model, see previous chapter. However, you need to add the new "History" tab manually to the work item types by modifying their XML definition files. For information on how to do this, please refer to the official Microsoft documentation (especially on how to modify and import processes). Apart from the import/export steps, the steps of modifying the actual XML file should be the same as for the "On-premises XML" process model outlined above.

Updating the extension

If the extension is installed from the marketplace and a newer version is available, it updates automatically. Azure DevOps Services (cloud) typically updates within a few minutes after a new version is released on the marketplace, while Azure DevOps Server (on-premises) might take roughly one day to pick up the latest version.

If the extension is not updated automatically in the on-premises variant after more than one day, you can try to update it manually: First, download the latest vsix package of the extension from the marketplace or GitHub. Then, in the web interface of your Azure DevOps Server, navigate to Collection Settings → Extensions → Browse local extensions (in the top right corner) → scroll down and select Manage extensions → then hover your mouse over the History Diff entry so that three dots ... appear to the right of the name → click the three dots → click Update and choose the vsix package → click Upload, and wait until the Verifying message disappears and the new version number appears next to the name of the History Diff extension. This may take a few seconds to a few minutes. The new version is now active.

About authentication requests in Firefox

In some environments Firefox might ask you to reenter your credentials when opening the history tab. This happens when Firefox tries to load resources not directly tied to a work item, such as the user avatars or other content (e.g. images) appearing in the work item's description field or comments. It seems that Chromium based browsers perform the necessary authentication automatically because they realize that your are logged into ADO itself, and the history page is served by the same origin. Firefox, on the other hand, treats the history page as separate and thus requests another authentication. There does not seem a way to tell Firefox to behave similar to the Chromium browsers. See THIS stackoverflow question for more technical details (and please get in touch in case you know the precise reason!).

Currently, I am aware of the following possibilities to cope with this issue:

• Just re-authenticate, even though it is annoying.
• Cancel the second authentication request. Avatars will most likely be missing, and some content in the diff (e.g. images) might not load.
• Use a different browser such as Google Chrome or Edge.
• Some companies employ single sign-on via the Windows NTLM protocol. If you can access the main ADO page without getting any authentication at all in Google Chrome or Edge, then this might have been setup by your IT department in the Windows settings. Chromium based browsers read the Windows settings value, but Firefox does not. The settings can be found in the "Internet Options", see the following image:
  
  You need to add the domains in this list to the Firefox settings:
  • Open Firefox.
  • Type about:config in the address bar, and accept the risk warning.
  • Filter for network.automatic-ntlm-auth.trusted-uris.
  • Add the end of the domains from the Windows settings, without the https:// and without *. Each entry matches the end of the domain. Separate multiple entries by a comma.

Future ideas

• Show pure formatting changes better. Implement it in my fork Sedeniono/htmldiff.js? Or use Wikipedia's VisualDiff from the VisualEditor (but has more dependencies). Or port DaisyDiff.
• Once markdown is available in Azure DevOps work items, support it.
• Support GitHub and remote work item links.
• Support test cases (Microsoft.VSTS.TCM.Steps, Microsoft.VSTS.TCM.LocalDataSource, Microsoft.VSTS.TCM.Parameters).
• Localization of hardcoded strings.