Skip to content

Latest commit

 

History

History
261 lines (195 loc) · 16.8 KB

README.md

File metadata and controls

261 lines (195 loc) · 16.8 KB
Raw

Azure DevOps History Diff

Introduction

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. Example comparison of the default ADO history with the new "History" tab

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 chapters further down for more details on how to install the extension.

Requirements:

  • Azure DevOps:
  • 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 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).

Details about the new "History" tab

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.

On-premise installation (Azure DevOps Server)

Uploading the extension to Azure DevOps Server

See the official Microsoft documentation. In short, you have to 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.

Distinguishing the "On-premises XML" from the "Inheritance" process 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.

"History" tab in the work item type configuration

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".

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 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.

Future ideas

  • 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.