Shopware

Appearance

2020-08-03 - Implement New Changelog

2020-08-03 - Implement New Changelog ​

INFO

This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository. You can find the original version here

Context ​

The current workflow for writing technical changelog is not very suited for a trunk based development and branching process. There are some major issues with the current workflow of using one file with a fixed version number:

  • Unnecessary merge conflicts in the changelog file
  • Uncertainty about the correct release version of the change
  • Differences between the issue state in Jira and the code state

To tackle these issues the technique for writing technical changelog and upgrade information, should be changed to a single solution, which is easy to understand and maintain by developers.

Decision ​

The changelog and upgrade files for a release should be autogenerated in the build process of the release. Developers should write technical changelog and upgrade information in separate markdown files.

Consequences ​

From the moment this ADR is accepted, every new changelog entry and upgrade information has to be recorded following the new workflow which is described in the following.

Workflow ​

For every feature or important code change there has to be a changelog markdown file in /changelog/_unreleased directory which follows the following naming convention:

{YYYY-MM-DD}-Meaningful-title-of-the-change.md
Example: 2020-08-03-New-CMS-components-for-3D-content.md

For simplicity there is a console command which helps you to create new changelog files: bin/console changelog:create [<title>] [options]. For a full list of options just use the --help flag of the command.

In the file all necessary changes are documented. The content of the file should always use the template which can be found in the /changelog/_template.md file. You can see a full example in the /changelog/_example.md file for a better understanding.

Meta Information ​

Next to the changelog information it is important to add the necessary meta information about your changes. Here is a detailed description of the meta information:

  • title (Required): Add a meaningful title. It can match the file name.

  • issue (Required): Add the corresponding Jira issue key. Can be the key of a single ticket or the key of an epic. For external contributions this is added by a shopware employee, when there is no corresponding issue in Jira yet.

  • flag: When you are developing a new feature, which is still behind a feature flag, you can add the flag in your changelog file during the development. Changelog files with an active flag will not be considered during a release. If you also do refactoring during the development of the feature which is not hidden behind a flag, create an additional changelog file for the changes of the refactoring.

  • author(Required): This field is optional for shopware employees, but required for all external developers. It can be used to identify the author of code changes, or to display the name in a changelog.

  • author_email(Required): This field is optional for shopware employees, but required for all external developers.

  • author_github (Optional): This is also mainly intended for external developers to get some reputation for the GitHub profile.

If you do not fill out some of the fields, please remove them from the file.

Changelog Entries ​

In the content of the file you add the technical changelog and upgrade information. The content is divided by first class headlines in the five categories:

  • Core
  • API
  • Administration
  • Storefront
  • Upgrade Information

In the sections under the headlines you add the corresponding information as list entries (* ), except the upgrade information. For each entry you have to use the corresponding keyword at the beginning of each entry:

  • Added
  • Removed
  • Changed
  • Deprecated

There should be no entry without one of the listed keywords. This is important to have a good consistency and also should it make you think about a meaningful description of your changes. So for example we do not allow the keyword "Fixed" as it leads to poor descriptions.

Example:

Bad changelog:
*  Fixed data binding issues in CMS elements.

Good changelog:
*  Changed method `registerCmsElement()` in `module/sw-cms/service/cms.service.js` to fix the mapping of the element data.

Have a look into the /changelog/_example.md file for some examples.

Upgrade Information ​

In the section for the upgrade information you add documentation in markdown for each part of your changes. Please use second class headlines in markdown (## ) to create new sections inside the upgrade information. You can use the content of /changelog/_template.md file as a start.

Release Workflow ​

When a new release is build, a new directory /changelog/release-6-x-x-x is created for the release. All changelog files in the /changelog/_unreleased directory are moved to the new release directory, except the files which have the flag meta information, because the changes are still behind a feature flag.

After the changelog files are moved to the corresponding release directory the main changelog file /CHANGELOG.md is updated by the build script. In the file a new section for the release is created, with a list of links to each single changelog file of the release. For the list entries the Jira ticket key and the title from the meta information is used.

Example:

## 6.3.1.0
*  [NEXT-12345 - Implemented cool new feature](/changelog/release-6-3-1-0/2020-08-05-Implemented-cool-feature)
*  [NEXT-56789 - Refactored an important service](/changelog/release-6-3-1-0/2020-08-03-Refactored-service)
...

Also a new UPGRADE-6.x.md file has to be generated, if it is a major release, or the corresponding existing file has to be updated with a new section, if it is a minor release. Other than the main CHANGELOG.md file, the upgrade files always contain the full content of the "Upgrade Information" sections of the changelog files. This is important, so that developers can read the upgrade information of a new version as a single document.

When do I have to create a changelog file ​

Of course not every change is worth a changelog file, but in most cases you will see, that it makes totally sense. So there should not be many reasons to not create a changelog file. Here are some rules which can help you:

  • New Feature: You are working on a new feature from the roadmap. Therefore you create a changelog file with the issue key of the Jira epic and collect all corresponding changes made for that feature. When the feature is that large, that it can be separated into smaller parts, you should create a file for each separate part. Don't forget to add the feature flag during the development of the feature.

  • Deprecations & Breaking Changes: You introduced new deprecations or breaking changes? Write a changelog!

  • Database Migrations: You have added new database migrations? Write a changelog!

  • External Code Changes: You are an external developer? Write a changelog!

Generating custom changelog ​

If you just want to get the changes of a specific version or even just a special part of Shopware, you can use a console command to generate the corresponding changelog.

bin/console changelog:change [<version>] [options]

Use the --help flag of the command to see all possible options.

Newsletter
Copyright © shopware AG - All rights reserved