Skip to content

Instantly share code, notes, and snippets.

@michaelbromley

michaelbromley/continuous-delivery-changelog.md

Forked from Jotschi/continuous-delivery-changelog.md
Last active May 16, 2022 09:48
Show Gist options
  • Save michaelbromley/f5df09ac6c336c61aa9578e9170698d2 to your computer and use it in GitHub Desktop.
Save michaelbromley/f5df09ac6c336c61aa9578e9170698d2 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
continuous-delivery-changelog.md

= Continuous Delivery Changelog

I have recently changed the Gentics Mesh release process from regular releases to a continous delivery release process. One of the questions that directly came up was how to manage a public changelog in continuous delivery workflow.

Previously (regular sequential releases) I would write the changelog entry upfront and since I knew what release version would be expected I could just refer to that version. With CD this changes. I can no longer refer to a specific version since I'm doing CD without actually knowing the version upfront.

I know that I could just fetch the SCM log and generate a changelog using that information but I don't like to use SCM messages for a public (enduser friendly) changelog. A changelog that just consists of SCM messages is way too noisy. Unfortunately it seems that all the open source changelog plugin utlize the git log to build a changelog.

For Gentics CMS I already wrote my own maven changelog plugin which is completely decoupled from the SCM. It maintains JSON files for each release and those JSON files contain lists of changelog entry files. This way any developer can create a bugfix branch, write the fix and add a changelog file. Once all fixes are merged back into the hotfix branch a release is built from that branch. During the release process all changelog entry files which have not yet been added to a release will automatically be assigned to the release that is currently being built. Additionally the maven plugin also takes care of maintaining a changelog for multiple releases (e.g.: 5.18.x, 5.19.x and 5.20.x).

For the Gentics Mesh we wanted to do something similar but less complicated. We therefore wrote the changelog2html tool. It does not need dedicated JSON files which need to be committed during release. Instead, the git SCM tag information is used to assign changelog entry files to specific tag versions.

The changelog workflow works like this:

  • Create a new changelog file with the name pattern [uuid].[changetype].md in your changes folder within your git project
  • Describe your change within that file. I suggest writing a styleguide for other developers
  • Once you are happy with your release, create a regular release and tag your sources using git
  • Run changelog2html over your changelog folder to generate your html changelog file
  • Publish the generated changelog.html file somewhere
  • Done
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment