Generating a list of changes between releases

6 Mar 2020

Read time: 4 minute(s)

Sometimes you may had PDFs or HTML content with the documentation to reviewers and instead of them having to read again the entire user's manual you may want to give them also a list of changed topics. Such a list can be manually maintained in a separate DITA topic but if your project uses version control and you tag your releases you may also want to try and manually build this list of changes.

For DITA projects which use Git for source control you can use a modified version of the DITA Open Toolkit custom ANT parser plugin to automatically generate a list of changes between two versions in the published output. I will enumerate the steps to do this below:

Check out your Git project. If all your releases are tagged as branches, running a command line like this:
```
git diff --name-only tagName
```
will show in the console a set of changed topics between the current changes and the tagName branch. For example for the Oxygen XML Editor user's manual I can run git diff --name-only oxygen22.0 to see all changes between the current contents in the repository and the Oxygen 22.0 branch in the repository.
In the main DITA Map add a reference to a topic which will be the recipient of the generated content at publishing time:
```
<topicref href="dynamicChangeHistory.gen" format="ant-parser"/>
```
Create this dynamicChangeHistory.gen topic next to the DITA Map but leave it with empty contents, the publishing plugin will be responsible of updating its contents.
Download the com.oxygenxml.ant.parser.dita plugin from here: https://github.com/oxygenxml/dita-custom-ant-parser/tree/generate-changes-list.
Integrate/install the plugin in your DITA Open Toolkit plugins folder.
Open the build file com.oxygenxml.ant.parser.dita/resources/build.xml in Oxygen XML Editor. The build file has three stages which may need to be slightly changed to fit your project's structure:
- Run the git command in your project's folder and find all differences related to a certain branch. In my case the branch is called oxygen22.0 so it needs to be changed to your particular branch name.
- Apply the XSLT stylesheet createChangesTopic.xsl on the changes list and generate a DITA topic. You will need to make changes to the stylesheet so that the generated paths to the changed topics are relative to the place where the generated DITA topic is located.
- Run an XSLT stylesheet on the DITA topic to add the @class attributes.
Once the plugin is properly configured, an extra topic will be produced in the output (either PDF or HTML) containing links to the changes list.