- Introduction
- Basic installation and requirements
- Details about the new "History" tab
- On-premise installation (Azure DevOps Server)
- Cloud installation (Azure DevOps Services)
- Future ideas
The standard history tab of work items in Azure DevOps (ADO) shows only the 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 and 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.
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.
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 chapters further down 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-clisomewhere to install the extension packaging tool (TFX) globally. - In the code's main directory, execute:
npm cito get the dependencies.npm run buildto create the vsix package (optimized release version) ornpm 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 to read 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).
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 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 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.
See the official Microsoft documentation. In short, you have to options:
- Option 1: Direct installation from the marketplace.
In the web interface of your Azure DevOps Server, go toCollection 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 → hitInstall→Proceed to collection. - Option 2: Manual upload of the vsix package.
-
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 selectManage extensions→ thenUpload extension(top right corner). -
Afterwards, on the
Browse local extensionspage, theHistory Diffextension should have appeared. Click on it →Get it free→ select the target collection from the drop down list → hitInstall→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.
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
witadmintool 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.
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.
The "on-premises XML" process model uses the witadmin tool.
-
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.
-
Export the definition of a work item type to XML:
witadmin exportwitd /collection:collectionurl /p:project /n:typename /f:filenameThe
typenameis the name of the work item type, e.g.Bug. Thefilenamespecifies the destination file; it should end with an.xmlextension. Runwitadmin exportwitd /helpfor additional details. -
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" /> ...
-
Import the modified XML file back into ADO:
witadmin importwitd /collection:collectionurl /p:project /f:filenamewhere
filenameis the path to the modified XML file.
Afterwards, the new "History" tab shows up in work items of the typetypenamespecified in the second step above. You need to do this for every work item type which should show the new "History" tab. -
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).
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".
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 above. 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.
- Show pure formatting changes. Maybe fork and try to improve htmldiff. Or possibly better, 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). - Show only the context of a change in longer descriptions (optionally).
- Localization of hardcoded strings.