[LOG4J2-3628] Migrate from maven-changes-plugin to a merge-conflict-free Markdown-based solution

• Type: Story
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 2.20.0
• Assignee: Volkan Yazici
• Reporter: Volkan Yazici
• Created: 07/Nov/22 20:52
• Updated: 16/Jan/23 21:13
• Resolved: 16/Jan/23 21:13

Description

As of date, Log4j project keeps its changelog using maven-changelog-plugin.
In a nutshell, developers register their entries to changes.xml and maven-changelog-plugin generates the report during Maven site phase.
This approach has certain drawbacks:

• maven-changelog-plugin hasn't been updated since 2016-10-29
• maven-changelog-plugin doesn't allow text style formatting (e.g., code blocks)
• maven-changelog-plugin doesn't allow an introduction paragraph. Everything needs to be a ticket; it is not possible to enhance the changelog of a release with "This release has mostly focused on bug fixes, yet we also shipped this awesome feature, ..." We work around this shortcoming via RELEASE-NOTES.md, which contradicts with the purpose of this plugin.
• maven-changelog-plugin doesn't generate a Markdown-formatted release note where one can simply copy paste to, say, a GitHub release. Developers manually duplicate its efforts in RELEASE-NOTES.md.
• maven-changelog-plugin source changes.xml constantly creates merge conflicts

I propose to replace maven-changelog-plugin and changes.xml with the following merge-conflict-free Markdown-based solution:

1. The changelogs of the released versions will be kept in changelogs/<yyyyMMdd>-<version>.md files (e.g., changelogs/20220223-2.17.2.md)
2. changelogs/<yyyyMMdd>-<version>.md files will be structured as described in keep a changelog, where tickets are grouped in following types: Added, Changed, Deprecated, Removed, Fixed, and Security
3. changelogs/index.md will keep an index of all changelogs/<yyyyMMdd>-<version>.md files
4. The changelog of the unreleased version will be kept in changelogs/unreleased directory
   1. changelogs/unreleased/<type>_<description>.md files will be used to register changes: Added_JTL_Jackson_fallback_support.md, Removed_SLF4J_1.8_bridge.md, etc. The contents of these files must be a single-line Markdown, since it will later be used in a Markdown bullet list.
   2. changelogs/unreleased/template.md will contain the Markdown file that will be used to render the final changelog just before a release. <div id="Tickets"/> will be replaced with a Markdown bullet list containing the files in the folder.
   3. changelogs/index.md and changelogs/<yyyyMMdd>-<version>.md files will be symlinked under src/site/markdown/changelogs directory
5. bin/generate-changelogs.sh script will perform the following tasks:
   1. generating a changelogs/<yyyyMMdd>-<version>.md from the contents of changelogs/unreleased
   2. removing all changelogs/unreleased/<type>_<description>.md files
   3. generating changelogs/index.md again

How does a changelogs/unreleased/template.md file look like?

The Apache Log4j 2 team is pleased to announce the Log4j <span id="revision"/> release!

This release primarily contains bug fixes and minor enhancements.

<div id="Tickets"/>

What shall I do when I am about to commit a change?

Add a changelogs/unreleased/<type>_<description>.md file along with your changes.

What shall I do when I am about to make a new Log4j release?

Update the version in the root pom.xml, call bin/generate-changelogs.sh, review and commit changes.
Now you can proceed with ./mvnw deploy.

What about the current changes.xml?

We will migrate all of its contents to changelogs/<yyyyMMdd>-<version>.md via a simple script and remove changes.xml.

Issue Links

• links to: GitHub Pull Request #1145
• links to: GitHub Pull Request #1146