It’s been a long trip that started in 2006. At this time, we were already using TFS to manage software development projects. The work items subsystem was newish at that time and we exported work items into Microsoft Word to generate specifications that can easily be handed over to reviewers. Later we started to close the gap between a fully integrated application lifecycle management system on the one hand and simple document editing on the other hand. Now, 14 years later we would like to open WordToTFS, a mature Azure DevOps integration for Microsoft Word, for community contributions and release version 7.0 as the latest major release that we have currently planned. In this blog post we would like to share some of our experiences while open sourcing a legacy application and finally wish you a happy holiday season.
How it all started
Approximately one year ago we decided to eventually open source WordToTFS. There are many reasons to do this. We have never placed it on the market as a commercial product. The original idea was to publish this for the community and involve customer’s funding into further development. In the meantime, there have been so many customer requirements incorporated into WordToTFS so that most of the further improvement is bug fixing and minor optimizations.
Additionally, it is a legacy application due to the underlying Azure DevOps Client Object Model. The migration to the REST API of Azure DevOps can hardly be done on a voluntary basis by a very small team of DevOps enthusiasts within AIT. Even more, instead of just renewing the API calls, it might be worth rethinking the major scenarios and separate them into smaller solutions. For instance, when authoring work items in Microsoft Word has been a very important use case when TFS had a poor user experience in the web user interface, it is a less important use case nowadays. Instead, we see WordToTFS mainly used for export functionality, e.g. to generate functional specifications or test reports. We are sure, open sourcing WordToTFS right now enables the community to better benefit from the parts they need. Nevertheless, we are happy to see Pull Requests from forks made by the users. Figure 1 shows the concept how the application can be built and deployed from now on.
Open sourcing 14 years old code
Open sourcing a legacy application comes along with a bunch of challenges. In the following we share some major steps we did to finally have the source code on GitHub today. As in every legacy code there is technical debt. Hence, we needed to clean up at least a minimum.
Before moving to GitHub, we maintained the source code on Azure DevOps. Hence, we were using the Azure DevOps Pipelines to build and deploy the application. For the move to GitHub we migrated to a YAML pipeline. Therefore, we carefully decided what parts of the build and deployment process need to be part of the actual build process rather than being part of the deployment mechanism. We ended with a solution to provide a YAML file containing the steps to build the application on any Azure DevOps Pipeline together with the source code on GitHub (ref. Figure 1).
Another challenge is to handle assets that cannot be published on GitHub due to legal obligations. Whenever somebody builds WordToTFS from a fork, we obviously do not want to show the AIT brand in logos etc. Therefore, we replaced all those assets in the GitHub repo with placeholder files. Whenever we build WordToTFS to publish it under the AIT brand, we replace the placeholder files with AIT branded assets.
Still build a branded version
We use an augmented pipeline, which is not published on GitHub. Like the aforementioned private assets, this Main.YAML file is part of a private repo (ref. Figure 2). Both, the publicly available source code as well as the private assets are merged and built into a single branded output by the Main.YAML build.
In addition, we use a Build and Release Pipeline, which is not part of the GitHub repo, to build and publish WordToTFS to the AIT website. Therefore, the public assets need to be merged with the private and branded assets.
Figure 2: Publish branded WordToTFS based on open source on GitHub
This allows the community to fix issues and improve the tool without the need of AIT development effort. However, this still enables us at AIT to release a branded version of WordToTFS while the actual product is open source. Hence, as shown in Figure 3, users of WordToTFS can still download the application from AIT’s web site (https://aitgmbh.de/wordtotfs).
Changes by the community
In addition to download the branded WordToTFS from the AIT website, a user can also fork the repo, make changes on his own and build the application using the provided YAML file as shown in Figure 4. Any Azure DevOps can be used as build engine. The migration of the build to GitHub actions is currently still an open topic.
There are some more challenges, e.g. regarding test data management. We explained this a bit in the Readme on GitHub.
AIT WordToTFS v7.0
As explained in the beginning of this article, we not only published the sources on GitHub, but we also released v7.0 of WordToTFS. The main content of this update is invisible work under the hood and addresses compatibility aspects. Since WordToTFS builds on the Client Object Model and therefore depends on the specific Visual Studio version, we updated all dependencies to use the current Visual Studio 2019 dependencies. In the former blog post, when we moved from WordToTFS v5 to WordToTFS v6, this is explained in detail. Please refer to https://www.aitgmbh.de/blog/news/wordtotfs-release-version-5-3-and-6-0-sim-shipped-with-visual-studio-2017/ section “HOW TO GET IT AND COMPATIBILITY”.
In addition, we fixed a bug regarding the date formatting property. When the date formatting property such as DateTimeFormat = “d” has been used, publishing a work item resulted in the following error: “Property is only supported for values coming from TFS/VSTS”.
Additionally, for more formal development processes, we added a definition for the Change Request work item. This can be found in the CMMI (2019) WordToTFS template.
Finally, a big thanks to all the users for their valuable feedback and contributions so far. A big thank you as well to the involved AIT developers for making it possible to open source WordToTFS just in time as an Xmas gift.
At AIT we are happy to make a present to the community in this special and challenging year. We wish all our customers and partners a happy holiday season as well as a prosperous 2021. Stay healthy and take care!