The file in our packages and extensions

Every package that we maintain at Liquid Light, be it private or open-source, all follow the same conventions.

One of those conventions is the and file contained within the repository. The denotes what has been released and is available and the details what is coming in the next one.


Our files all follow the same format - a real-world example can be found in our TYPO3 extension repository - TYPO3 Shortcodes.

The format is as follows:

  • The version number as a h1
  • The release date in bold underneath
  • Each change summarised in a human readable format, categorised under a sub-heading - which generally follow the type from the commits (as defined in Conventional Commits)

We originally generated our changelog files from the commits - however that is no different to running a git log in the repository. Instead, we describe the change best we can - linking to related issues or MRs. This also allows us to group several commits into one "change" if desired. It also means linting and other chores can be excluded from the changelog.


This is where the file comes into play. It serves as a working document as is a requirement for Merge/Pull Requests.

When adding to the repository with a feature or a bug fix, the file must be updated. It follows the same convention as the and means the contents can be copied and pasted when it comes to being released.

The only difference in the format of the file is the title. In the CHANGELOG, the h1 is the release version, however in the UPCOMING it is either Major, Minor or Patch/Bug.

The title is determined by the developer adding the change and can be updated in the life-cycle.

This allows Merge Requests to be merged into several different between versions for backward compatibility. It also allows Merge Requests to wait, should another need to be merged and released and the file not need updating. Keeping these changes in a separate file also means the file stays clean.

An example flow might be:

  1. Developer A creates a merge request for a bug and carries out the work
  2. They update the with a title of Bug and describe the issue
  3. Their change is accepted and merged.
  4. Developer B wishes to add a feature - a new MR is created and the feature added
  5. They add their description to the file and, in doing so, updates the title from a Bug to Minor
  6. Once merged and ready to be released, the contents is copied to the top of the file and the title replaced to the corresponding version.

View this post on Github

You might also enjoy…

Mike Street

Written by Mike Street

Mike is a CTO and Lead Developer from Brighton, UK. He spends his time writing, cycling and coding. You can find Mike on Mastodon.