Generating a Change Log

In this tutorial, you'll learn how to automatically generate an effective changelog using Git commit messages and integrate it into an Azure Pipeline. By following the steps below, you can ensure your project wiki stays continuously updated with the latest commit information.

1. Creating a Basic Changelog with Git

To get started, generate a simple list of commit messages in reverse chronological order using Git’s log command. Run the following command in your repository:

git log --pretty=format:"- %s" --reverse

This command outputs a concise list of commit messages that you can save into a Markdown file for your project documentation or wiki.

2. Enhancing Your Changelog with Detailed Information

For a changelog that provides more context, including commit hashes, author names, and relative commit times, use the enhanced Git log format below:

git log --pretty=format:"%h - %s (%an, %ar)" --reverse

This command delivers a detailed view of the commit history, making it easier to track what changes were made, by whom, and when.

3. Automating Changelog Generation in Azure Pipelines

Integrate the changelog generation into your Azure Pipelines workflow using the YAML configuration provided below. This pipeline performs the following tasks:

• Generates release notes using the XplatGenerateReleaseNotes task.
• Captures the Git log output into a CHANGELOG.md file.
• Copies both the release notes and CHANGELOG.md to the wiki folder.
• Commits the updates back to the repository.

- task: XplatGenerateReleaseNotes@4
  inputs:
    checkForManuallyLinkedWI: False
    wikiFromTarget: WorkItems

- task: CopyFiles@2
  displayName: 'Copy Release Notes to Wiki Folder'
  inputs:
    SourceFolder: '$(Build.Repository.LocalPath)'
    Contents: 'releasenotes_$(Build.BuildId).md'
    TargetFolder: '$(Build.Repository.LocalPath)/wiki'
    CleanTargetFolder: true
    OverWrite: true

- script: |
    del "$(Build.Repository.LocalPath)\releasenotes_$(Build.BuildId).md"
  displayName: 'Delete Original Release Notes File'

- task: PowerShell@2
  displayName: 'Run Git command and capture changelog to output'
  inputs:
    targetType: 'inline'
    script: |
      git log --pretty=format:"%h - %s (%an, %ar)" --reverse | ForEach-Object { Add-Content -Path CHANGELOG.md -Value $_ }

- task: CopyFiles@2
  displayName: 'Copy Changelog to Wiki Folder'
  inputs:
    SourceFolder: '$(Build.Repository.LocalPath)'
    Contents: 'CHANGELOG.md'
    TargetFolder: '$(Build.Repository.LocalPath)/wiki'
    CleanTargetFolder: true
    OverWrite: true

- task: CmdLine@2
  displayName: 'Commit everything to Wiki Folder'
  inputs:
    script: |
      git checkout master
      git pull
      git config --global user.email "[email protected]"
      git config --global user.name "Jeremy Morgan"
      git commit -m "[skip ci] Update changelog for $(Build.BuildId) in wiki folder"
      git push origin HEAD:master

In this pipeline:

• The XplatGenerateReleaseNotes task automatically creates release notes.
• The CopyFiles tasks move the generated release notes and the custom changelog (CHANGELOG.md) into the designated wiki folder.
• A PowerShell script runs the Git log command and appends the output to CHANGELOG.md.
• Finally, a CmdLine task checks out the master branch, synchronizes with the remote repository, and commits the updated changelog.

4. Pipeline Execution and Verification

After you commit and push your changes, the pipeline executes automatically. Monitor the progress within Azure DevOps. The image below illustrates a summary of a successful pipeline run for the "TestWeb" project:

Once the pipeline finishes, the changelog (CHANGELOG.md) is copied to the wiki folder and committed to the repository. To verify the outcome, navigate to your wiki and ensure the changelog reflects the most recent commits.

The snippet below from the job log details the file copy process for CHANGELOG.md:

Starting: Copy Changelog to Wiki Folder
==================================================================
Task          : Copy files
Description   : Copy files from a source folder to a target folder using patterns matching file paths (not folder paths)
Version       : 2.238.0
Author        : Microsoft Corporation
Help          : http://docs.microsoft.com/azure/devops/pipelines/tasks/utility/copy-files
==================================================================

Found 1 files
Cleaning target folder: C:\Users\Jeremy\Downloads\agent_work\7\s\wiki
Copying: C:\Users\Jeremy\Downloads\agent_work\7\CHANGELOG.md to C:\Users\Jeremy\Downloads\agent_work\7\s\wiki\CHANGELOG.md
Finishing: Copy Changelog to Wiki Folder

Additionally, review the following image that displays the changelog page from Azure DevOps, highlighting recent updates and commits:

Conclusion

By following these steps, you can automate the generation of a detailed changelog from your Git commit history and seamlessly integrate it into your project wiki via Azure Pipelines. This automated approach ensures that your documentation remains current with every update, streamlining your development workflow.

Thank you for reading this guide. We hope these techniques prove beneficial in enhancing your project’s documentation and deployment processes.