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

["Volkan Yazici (Jira)" <ji...@apache.org>]

Volkan Yazici created LOG4J2-3628:
-------------------------------------

             Summary: Migrate from maven-changes-plugin to a merge-conflict-free Markdown-based solution
                 Key: LOG4J2-3628
                 URL: https://issues.apache.org/jira/browse/LOG4J2-3628
             Project: Log4j 2
          Issue Type: Story
            Reporter: Volkan Yazici
             Fix For: 2.20.0


As of date, Log4j project keeps its changelog using [maven-changelog-plugin|https://maven.apache.org/plugins/maven-changes-plugin/].
In a nutshell, developers register their entries to {{changes.xml}} and {{maven-changelog-plugin}} generates [the report|https://logging.apache.org/log4j/2.x/changes-report.html] 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|https://github.com/apache/logging-log4j2/releases]. 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:
 # The changelogs of the *released* versions will be kept in {{changelogs/<yyyyMMdd>-<version>.md}} files (e.g., {{{}changelogs/20220223-2.17.2.md{}}})
 # {{changelogs/<yyyyMMdd>-<version>.md}} files will be structured as described in [keep a changelog|https://keepachangelog.com/en/1.0.0/], where tickets are grouped in following types: Added, Changed, Deprecated, Removed, Fixed, and Security
 # {{changelogs/index.md}} will keep an index of all {{changelogs/<yyyyMMdd>-<version>.md}} files
 # The changelog of the *unreleased* version will be kept in {{changelogs/unreleased}} directory
 ## {{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.
 ## {{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.
 ## {{changelogs/index.md}} and {{changelogs/<yyyyMMdd>-<version>.md}} files will be symlinked under {{src/site/markdown/changelogs}} directory
 # {{bin/generate-changelogs.sh}} script will perform the following tasks:
 ## generating a {{changelogs/<yyyyMMdd>-<version>.md}} from the contents of {{changelogs/unreleased}}
 ## removing all {{changelogs/unreleased/<type>_<description>.md}} files
 ## generating {{changelogs/index.md}} again

h3. How does a {{changelogs/unreleased/template.md}} file look like?
{code:java}
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"/>
{code}
h3. What shall I do when I am about to commit a change?

Add a {{changelogs/unreleased/<type>_<description>.md}} file along with your changes.
h3. 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{}}}.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)